IBM® Cognos® 8 Planning - Contributor Administration Guide

IBM ® Cognos ® 8 Planning
CONTRIBUTOR
ADMINISTRATION GUIDE

Product Information
This document applies to IBM ® Cognos ® 8 Planning Version 8.4 and may also apply to subsequent releases. To check for newer versions of
this document, visit the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html).
Copyright
Copyright © 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC is an IBM Company.
Portions of Cognos ULC software products are protected by one or more of the following U.S. Patents: 6,609,123 B1; 6,611,838 B1; 6,662,188
B1; 6,728,697 B2; 6,741,982 B2; 6,763,520 B1; 6,768,995 B2; 6,782,378 B2; 6,847,973 B2; 6,907,428 B2; 6,853,375 B2; 6,986,135 B2;
6,995,768 B2; 7,062,479 B2; 7,072,822 B2; 7,111,007 B2; 7,130,822 B1; 7,155,398 B2; 7,171,425 B2; 7,185,016 B1; 7,213,199 B2; 7,243,106
B2; 7,257,612 B2; 7,275,211 B2; 7,281,047 B2; 7,293,008 B2; 7,296,040 B2; 7,318,058 B2; 7,325,003 B2; 7,333,995 B2.
Cognos and the Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated) in the United States and/or other countries. IBM
and the IBM logo are trademarks of International Business Machines Corporation in the United States, or other countries or both. Java and
all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product,
or service names may be trademarks or service marks of others.
While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or
technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained
in this document.
This document shows the publication date. The information contained in this document is subject to change without notice. Any improvements
or changes to the information contained in this document will be documented in subsequent editions.
U.S. Government Restricted Rights. The software and accompanying materials are provided with Restricted Rights. Use, duplication, or disclosure
by the Government is subject to the restrictions in subparagraph (C)(1)(ii) of the Rights in Technical Data and Computer clause at
DFARS 252.227-7013, or subparagraphs (C)(1) and (2) of the Commercial Computer Software - Restricted Rights at 48CFR52.227 as applicable.
The Contractor is Cognos Corporation, 15 Wayside Road, Burlington, MA 01803.
This document contains proprietary information of Cognos. All rights are reserved. No part of this document may be copied, photocopied,
reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior
written consent of Cognos.

Table of Contents
Introduction 13
Chapter 1: What’s New? 17
New Features in Version 8.4 17
Load A-Tables Using Administration Links 17
New Contributor Web Client 17
Improved Performance During Incremental Publish 17
Additional Support for Built-in Functions 17
IBM Cognos 8 Business Viewpoint Client Integration 17
New Features in Version 8.3 18
Extended Language Support 18
Microsoft Vista Compliance 18
Microsoft Excel 2007 18
Select Folders in IBM Cognos Connection 18
Select a Framework Manager Package for an Administration Link 19
Chapter 2: IBM Cognos 8 Planning - Contributor 21
Extending the Functionality of the Contributor Administration Console and the Classic Contributor
Web Client 21
Using Contributor Applications 21
Cubes 21
Dimensions 21
e.Lists 21
Access Tables and Saved Selections 22
D-Links 22
Managing Contributor Applications 22
Multiple Administrators 22
Moving Data 22
System Links 23
Automating Contributor Tasks Using Macros 23
Publishing Data 23
Creating a Contributor Application 23
Developing the Plan in Analyst 24
Designing the e.List 24
Assigning Rights 24
Creating the Application 24
Creating the Production Application 25
Running Jobs 25
Testing the Web Site 25
The Administrator 25
The Planner 26
The Reviewer 26
The Toolbar 27
Administration Guide 3

Table of Contents
4 Contributor
Chapter 3: Security 29
Cognos Namespace 29
Authentication Providers 29
Deleting or Restoring Unconfigured Namespaces 31
Users, Groups, and Roles 31
Users 32
Groups and Roles 32
Setting up Security for an IBM Cognos 8 Planning Installation 34
Configure IBM Cognos 8 to Use an Authentication Provider 35
Add or Remove Members From Planning Rights Administrators and Planning Contributor
Users Roles 36
Enabling Planning Roles in IBM Cognos 8 37
Restricting Access to the Everyone Group 37
Recommendation - Creating Additional Roles or Groups for Contributor 37
Configuring Access to the Contributor Administration Console 38
Granting Access Rights to Administrators 39
Access Rights for Macros 42
Assign Scheduler Credentials 44
Chapter 4: Configuring the Administration Console 47
Creating Planning Tables 47
Add a Datastore Server 48
Datastore Server Information 49
Jobs 49
Types of Jobs 49
Run Order for Jobs 50
Actions That Cause Jobs to Run 51
Securing Jobs 51
Managing Jobs 52
Reconciliation 54
Deleting Jobs 55
Managing Job Servers 55
Manage a Job Server Cluster 56
Add a Job Server and Change its Content Store 56
Add Applications and Other Objects to a Job Server Cluster 57
Add Objects to a Job Server 58
Remove Job Servers 59
Monitor Application Folders 59
Creating, Adding and Upgrading Applications 60
Remove Datastore Definitions and Contributor Applications 60
Adding an Existing Application to a Datastore Server 60
The Monitoring Console 61
Managing Sessions 61
Sending Email 63
Chapter 5: Creating a Contributor Application 65
Creating a Contributor Application 65
Application Folders 68
Model Details 68

Running the Script.sql file (DBA Only) 69
Application Information 70
Configuring the Contributor Application 70
Configure the Web Client 71
Set the Cube Order for an Application 71
Set the Order of Axes 72
Change Grid Options 72
Change Application Options 74
Create Planner-Only Cubes 78
Creating General Messages and Cube Instructions 78
Maintaining the Contributor Application 79
Save Application XML for Support 79
View Application Details 79
Admin Options 79
Select Dimensions for Publish 82
Set Go to Production Options 82
Datastore Options 84
Chapter 6: The Contributor Web Client Application 87
The Contributor Web Site 87
The Tree 87
The Table 87
Set Web Site Language 88
Access Contributor Applications 88
Configure Classic Contributor Web Client Security Settings 89
Linking to Earlier Versions of Contributor Applications 89
Working Offline 89
The Offline Store 90
Independent Web Applications 90
Contributor for Microsoft Excel 91
Chapter 7: Managing User Access to Applications 93
The e.List 93
Multiple Owners of e.List Items 95
Import e.List and Rights 96
Export the e.List and Rights 101
Managing the e.List 101
Rights 107
Actions Allowed for Review e.List Items 108
Actions Allowed for Contribution e.List items 109
Rights File Formats 110
Modify Rights Manually 111
Validating Users, Groups and Roles in the Application Model and Database 113
Chapter 8: Managing User Access to Data 115
Saved Selections 115
Editing Saved Selections 116
Access Tables 119
Access Tables and Cubes 119
Rules for Access Tables 120
Table of Contents
Administration Guide 5

Table of Contents
6 Contributor
Creating Access Tables 123
Large Access Tables 129
Multiple Access Tables 135
Changes to Access Tables That Cause a Reconcile Job to Be Run 136
Access Tables and Import Data 137
Access Levels and Contributor Data Entry 137
Force to Zero 137
Reviewer Access Levels 137
Cut-down Models 138
When Does the Cut-down Models Process Happen? 138
Limitations 138
Cut-down Model Options 139
Cut-down Models and Translation 139
Cut-down Models and Access Tables 140
Restrictions to Cutting Down Dimensions 140
Estimating Model and Data Block Size 141
Cut-down Model Example 142
Chapter 9: Managing Data 143
Understanding Administration, System, and Local Links 144
Using Links to Move Data Between Cubes and Applications 145
Using Links in Model Design 146
Administration Links 147
Create an Administration Link 149
Map Dimensions Manually 154
Use an Allocation Table in Administration Links 155
Validate Administration Links 156
Synchronize Administration Links 156
View Items in a Dimension 157
Remove a Dimension 157
Running Administration Links 157
Exporting and Importing Administration Links 157
Tuning Administration Links 158
System Links 162
Create a System Link 163
Importing Data from IBM Cognos 8 Data Sources 164
Create a Framework Manager Project and Import Metadata 165
Create and Publish the IBM Cognos Package 166
Working with SAP BW Data 167
Recommendation - Query Items 168
Recommendation - Hierarchy 168
Recommendation - Hiding the Dimension Key Field 169
Working with Packages 169
Troubleshooting Detailed Fact Query Subject Memory Usage 169
Deploying the Planning Environment and Viewing the Status of Deployments 170
Export a Model 170
Import a Model 170
View the Status of Existing Deployments 172
Troubleshooting Out of Memory Exception When Exporting During a Deployment 173

Importing Text Files into Cubes 173
Creating the Source File 173
Select the Cube and Text File to Load into the Cube 175
Load the Data into the Datastore 175
Prepare the Import Data Blocks 176
Chapter 10: Synchronizing an Application 179
Changes that Result in Loss of Data 179
Synchronizing an Application 180
Generate Scripts 180
How to Avoid Loss of Data 180
Example Synchronization 181
Advanced - Model Changes 182
Chapter 11: Translating Applications into Different Languages 185
Assigning a Language Version to a User 185
Translate the Application 186
Translate Strings Using the Administration Console 187
Exporting and Importing Files for Translation 189
Export Files for Translation 190
Import Translated Files 190
Search for Strings in the Content Language or Product Language Tab 191
Translating Help 191
System Locale and Code Pages 191
About Fonts 192
Chapter 12: Automating Tasks Using Macros 193
Common Tasks to Automate 193
Creating a Macro 194
Create a New Macro 194
Create a Macro Step 195
Transferring Macros and Macro Steps 198
Job Servers (Macro Steps) 199
Development (Macro Steps) 202
Production (Macro Steps) 211
Administrator Links (Macro Steps) 219
Macros (Macro Steps) 220
Session (Macro Steps) 223
Running a Macro 224
Run a Macro from Administration Console 225
Run a Macro from IBM Cognos Connection 225
Run a Macro from an IBM Cognos 8 Event 226
Run a Macro using Macro Executor 227
Run a Macro using Command Line 228
Run a Macro using Batch File 228
Troubleshooting Macros 229
Unable to Run Contributor Macros Using a Batch File 229
Chapter 13: Data Validations 231
Setting Up Data Validation 232
Table of Contents
Administration Guide 7

Table of Contents
8 Contributor
The Impact of Aggregation on Validation Rules 233
Define a Validation Rule 237
Define or Edit a Rule Set 239
Edit a Validation Rule 240
Associate Rule Sets to e.List Items 240
Chapter 14: The Go to Production Process 243
Planning Packages 244
Reconciliation 245
The Production Application 245
Model Definition 245
Data Block 245
Production Tasks 246
Cut-down Models and Multiple Languages 246
The Development Application 247
Development Model Definition 247
Import Data Blocks 247
Run Go to Production 248
Go to Production Options Window 248
Show Changes Window 249
Model Changes Window 250
Import Data Details Tab 254
Invalid Owners and Editors Tab 254
e.List Items to be Reconciled Tab 256
Cut-down Models Window 256
Finish Window 256
Chapter 15: Publishing Data 259
The Publish Data Store Container 260
Access Rights Needed for Publishing 260
Publish Scripts 260
Selecting e.List Items to Be Published 261
Reporting Directly From Publish Tables 261
Model Changes that Impact the Publish Tables 262
Data Dimensions for Publish 263
Selecting a Dimension for Publish for Reporting 264
The Table-Only Publish Layout 265
Database Object Names 266
Items Tables for the Table-only Layout 267
Hierarchy Tables for the Table-only Layout 267
Export Tables For the Table-only Layout 270
Annotations Tables for the Table-only Layout 271
Attached Document Tables for the Table-only Layout 272
Metadata Tables 274
Common Tables 276
Job Tables 276
The P_OBJECTLOCK Table 277
Create a Table-only Publish Layout 277
Options for Table-only Publish Layout 278
Create an Incremental Publish 279

The View Publish Layout 279
Database Object Names 280
Items Tables for the View Layout 281
Hierarchy Tables for the View Layout 281
Export Tables for the View Layout 282
Annotation Tables for the View Layout 282
Views 283
Create a View Layout 283
Options for View Layout 284
Create a Custom Publish Container 285
Configure the Datastore Connection 286
Remove Unused Publish Containers 288
Chapter 16: Commentary 289
User and Audit Annotations 289
Delete Commentary 289
Delete Commentary - e.List items 289
Deleting Commentary 290
Configuring the Attached Documents Properties 290
Publishing Attached Documents 291
Copy Commentary 291
Breakback Considerations when Moving Commentary 291
Chapter 17: Previewing the Production Workflow 293
Previewing e.List item Properties 293
Preview Properties - General 293
Preview Properties - Owners 294
Preview Properties - Editors 294
Preview Properties - Reviewers 294
Preview Properties - Rights 295
Workflow State Definition 295
Additional Workflow States 296
Workflow State Explained 296
Chapter 18: Using Contributor With Other IBM Cognos Products 299
Table of Contents
Client and Admin Extensions 300
Classic Client Extensions 300
Admin Extensions 301
Integrating with IBM Cognos Business Intelligence Products 302
Using IBM Cognos 8 BI with Contributor Unpublished (Real-Time) Data 302
The Generate Framework Manager Model Admin Extension 306
Generate Transformer Model 309
Excel and Contributor 311
Design Considerations When Using Contributor for Excel 311
Print to Excel for Classic Contributor Web Client 312
Export for Excel for Classic Contributor Web Client 312
Financial Planning with IBM Cognos Performance Applications and Planning 312
Managing Contributor Master Dimensions with IBM Cognos 8 Business Viewpoint Client 314
Launching Business Viewpoint Client from Contributor 314
Administration Guide 9

Table of Contents
10 Contributor
Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products 315
Download and Deploy the Sample 315
Example of Integration with IBM Cognos 8 Business Intelligence 316
Run a Contributor Macro to Import Data 317
Create and Publish a Framework Manager Package 317
Create a Report 319
Create an Event Studio Agent 327
Chapter 20: Upgrading IBM Cognos 8 Planning - Contributor 329
Upgrade the Planning Administration Domain 329
Upgrade Contributor Applications 332
Upgrade Security 335
Accessing Contributor Applications 336
Chapter 21: Analyst Model Design Considerations 337
Designing an Analyst Model for Contributor 337
Analyst Library Guidelines 337
D-Cube Restrictions 338
D-Links 339
Dimensions 341
Creating Applications with Very Large Cell Counts 345
Break-Back Differences Between Analyst and Contributor 346
AnalystContributor Links 347
Set Up a Link Between Analyst and Contributor and Between Contributor Applications 348
Analyst>Contributor D-Links 348
Contributor>Analyst Links 349
Contributor>Contributor links 349
Copying AnalystContributor Links 350
Links and Memory Usage 351
Update a Link from a Computer That Cannot Access the Original Datastore 351
Multiple D-Links Using the @DLinkExecuteList Macro 352
Run D-Links While Making Model Changes 352
Effects of Fill and Substitute Mode on Untargeted Cells 353
Effect of Access Tables in Contributor 354
Appendix A: DB2 UDB Supplementary Information 355
The Contributor Datastore 355
Requirements for the DB2 UDB Database Environment 355
Background Information For DB2 UDB DBAs 356
Security and Privileges 356
Naming Conventions 357
Metadata 357
Backup 357
Standards 357
Preventing Lock Escalation 358
Large Object Types 358
Job Architecture 358
Importing and Reporting Data 359
Reporting Data: Understanding the Publish Job Process 359
Data Loading 360

Job Failure 360
Appendix B: Troubleshooting the Generate Framework Manager Model Extension 361
Unable To Connect to the Database While Using Oracle 361
Unable to Create Framework Manager Model 361
Unable to Retrieve Session’s Namespace 362
Unable to Change Model Design Language 362
Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages 363
Limitations for Importing IBM Cognos Packages 363
Troubleshooting Modeled Data Import 366
Viewing Generated Files 366
Using Error Messages to Troubleshoot 369
Techniques to Troubleshoot Problems with an Import 372
Appendix D: Customizing IBM Cognos 8 Planning - Contributor Help 375
Creating Cube Help 375
Detailed Cube Help 375
Using HTML Formatting 375
Using Images, Hypertext Links, and E-Mail Links in Contributor Applications 377
Appendix E: Error Handling 379
Error Logs and History Tracking 379
Application XML issues 380
Timeout Errors 380
History Tracking 380
Calculation Engine (JCE) error logs 382
General Error Logging 383
How Errors are Logged in the Administration Console 383
Using the LogFetcher Utility 385
Appendix F: Illegal Characters 387
Appendix G: Default Options 389
Grid Options 389
Application Options 389
XML Location and Filename 390
Admin Options 390
Go to Production Options 391
Go to Production Wizard Options 391
Publish Options-View Layout 392
Publish Options-Table Only Layout 392
e.List 393
Rights 393
Access Tables 393
Delete Commentary 394
Appendix H: Data Entry Input Limits 395
Limits For Text Formatted Cells 395
Limits for Numerical Cells 395
Table of Contents
Administration Guide 11

Table of Contents
12 Contributor
Glossary 397
Index 405

Introduction
This document is intended for use with the IBM Cognos 8 Planning - Contributor Administration
Console. This guide describes how to use the Contributor Administration Console to create and
manage Contributor applications.
IBM Cognos 8 Planning provides the ability to plan, budget, and forecast in a collaborative, secure
manner. The major components are Analyst and Contributor.
IBM Cognos 8 Planning - Analyst
Analyst is a flexible tool used by financial specialists to define their business models. These models
include the drivers and content required for planning, budgeting, and forecasting. The models can
then be distributed to managers using the Web-based architecture of IBM Cognos 8 Planning -
Contributor.
IBM Cognos 8 Planning - Contributor
Contributor streamlines data collection and workflow management. It eliminates the problems of
errors, version control, and timeliness that are characteristic of a planning system solely based on
spreadsheets. Users have the option to submit information simultaneously through a simple Web
or Microsoft Excel ® interface. Using an intranet or secure Internet connection, users review only
what they need to review and add data where they are authorized.
For more information about using this product, visit the IBM Cognos Resource Center (http://www.
ibm.com/software/data/support/cognos_crc.html).
Best Practices for IBM Cognos 8 Planning
The Cognos Innovation Center for Performance Management provides a forum and Performance
Blueprints that you can use to discover new ideas and solutions for finance and performance man-
agement issues. Blueprints are pre-defined data, process, and policy models that incorporate best
practice knowledge from customers and the Cognos Innovation Center. These Blueprints are free
of charge to existing customers or Platinum and Gold partners. For more information about the
Cognos Innovation Center or the Performance Blueprints, visit http://www.cognos.com/
innovationcenter.
Audience
To use this guide, you should have an understanding of IBM Cognos 8 Planning - Analyst. Some
knowledge of security and database systems would also be helpful.
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.
Administration Guide 13

Introduction
14 Contributor
Note: For online users of this document, a Web page such as The page cannot be found may appear
when clicking individual links in the following table. Documents are made available for your par-
ticular installation and translation configuration. If a link is unavailable, you can access the document
on the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html).
Document
Analyst User Guide
Contributor Web Client
User Guide
Contributor for Microsoft
Excel® User Guide
IBM Cognos Connection
User Guide
IBM Cognos 8 Administra-
tion and Security Guide
Framework Manager User
Guide
Guidelines for Modeling
Metadata
Event Studio User Guide
Finding Information
Description
Using IBM Cognos 8 Planning - Analyst
Using the IBM Cognos 8 Planning - Contributor Web client
Using the IBM Cognos 8 Planning - Contributor for Microsoft Excel®
Using IBM Cognos Connection to publish, find, manage, organize,
and view IBM Cognos content, such as scorecards, reports, analyses,
and agents
Managing servers, security, reports, and portal services; and setting
up the samples, customizing the user interface and troubleshooting
Creating and publishing models using Framework Manager
Recommendations for modeling metadata to use in business reporting
and analysis
Creating and managing agents that monitor data and perform tasks
when the data meets predefined thresholds
Product documentation is available in online help from the Help menu or button in IBM Cognos
products.
To find the most current product documentation, including all localized documentation and
knowledge base materials, access the IBM Cognos Resource Center (http://www.ibm.com/software/
data/support/cognos_crc.html).
You can also read PDF versions of the product readme files and installation guides directly from
IBM Cognos product CDs.
Getting Help
For more information about using this product or for technical assistance, visit the IBM Cognos
Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html). This site provides
information on support, professional services, and education.

Printing Copyright Material
You can print selected pages, a section, or the whole book. You are granted a non-exclusive, 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 IBM
Cognos software.
Introduction
Administration Guide 15

Introduction
16 Contributor

Chapter 1: What’s New?
This section contains a list of new features for this release. It also contains a cumulative list of
similar information for previous releases. It will help you plan your upgrade and application
deployment strategies and the training requirements for your users.
For information about upgrading, see the IBM Cognos 8 Planning Installation and Configuration
Guide.
For information about new features for this release, see the IBM Cognos 8 Planning New Features
Guide.
For changes to previous versions, see New Features in Version 8.3.
To review an up-to-date list of environments supported by IBM Cognos products, such as operating
systems, patches, browsers, Web servers, directory servers, database servers, and application servers,
visit the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.
html).
New Features in Version 8.4
Listed below are new features since the last release. Links to directly-related topics are included.
Load A-Tables Using Administration Links
This release supports loading of A-Tables into Contributor using Administration Links. For more
information, see "Create an Administration Link" (p. 149).
New Contributor Web Client
This release provides a new Contributor Web Client. For more information, see the IBM Cognos 8
Planning - Contributor Web Client User Guide.
Improved Performance During Incremental Publish
This release provides changes to incremental publish to increase performance. For more information,
see "Create an Incremental Publish" (p. 279)
Additional Support for Built-in Functions
This release includes more built-in functions that are available for use in Contributor. For more
information, see "Supported BiFs" (p. 343).
IBM Cognos 8 Business Viewpoint Client Integration
You can launch the new Business Viewpoint Client from Contributor. With Business Viewpoint
Client, you can nominate master dimensional data from Contributor into a Business Viewpoint
Administration Guide 17

Chapter 1: What’s New?
Studio master repository, subscribe to Business Viewpoint Studio master dimensional data, and
update the data to ensure it is synchronized between the two sources. From within Business Viewpoint
Client, you can also open the Business Viewpoint Studio.
For information on how to use the Business Viewpoint Client with Contributor, see the IBM Cognos
8 Business Viewpoint Client User Guide. You can access it after you launch Business Viewpoint
Client.
New Features in Version 8.3
Listed below are new features in version 8.3. Links to directly-related topics are included.
Extended Language Support
This release provides support for Japanese and Swedish product strings. Contributor Web Client
strings can be translated into these languages without the need to enter translation strings. Japanese
and Swedish language content strings are also supported. For more information, see the following
sections.
● "Translating Applications into Different Languages" (p. 185)
● "Set Web Site Language" (p. 88)
Microsoft Vista Compliance
Microsoft Excel 2007
The Contributor Web application and Contributor for Excel can be used with Microsoft Vista. For
more information about installing and using Vista, see the IBM Cognos 8 Planning - Contributor
for Microsoft Excel ® Installation Guide. For more information about using Contributor with Excel
or the Contributor Web application, see the Contributor for Microsoft Excel ® User Guide and
Contributor Browser User Guide.
This release supports Contributor and Analyst for Excel using Microsoft Excel 2007. For more
information about using Analyst or Contributor with Excel, see the Analyst for Microsoft Excel ®
User Guide and Contributor for Microsoft Excel ® User Guide.
Select Folders in IBM Cognos Connection
18 Contributor
This release supports folder selection in IBM Cognos Connection when generating Framework
Manager and Transformer models. For more information, see the following sections.
● "Run the Generate Framework Manager Model Admin Extension" (p. 308)
● "Generate Transformer Model" (p. 309)

Select a Framework Manager Package for an Administration Link
This release supports browsing in IBM Cognos Connection folders to select a Framework Manager
package for an Administration Link. For more information, see "Steps to Create Links with IBM
Cognos Package as the Source" (p. 151).
Chapter 1: What’s New?
Administration Guide 19

Chapter 1: What’s New?
20 Contributor

Chapter 2: IBM Cognos 8 Planning - Contributor
IBM Cognos 8 Planning - Contributor is a Web-based planning platform that can involve thousands
of people in the planning process, collecting data from managers and others, in multiple locations.
Complex calculations are performed on the Web client showing totals as soon as data is entered,
preventing unnecessary traffic on the server during busy times. Information is then stored in a data
repository, providing an accurate and single pool of planning data.
In addition, users can use Contributor for Excel to view and edit Contributor data using Excel.
Administrators use the Contributor Administration Console to create and configure Contributor
applications, manage access settings, distribute IBM Cognos 8 Planning - Analyst business plans,
and configure the user's view of the business plan.
Extending the Functionality of the Contributor Administration
Console and the Classic Contributor Web Client
Extensions are provided that extend the functionality of the Contributor Administration Console
and the Classic Contributor Web Client. There are two types of extensions: Admin Extensions and
Client Extensions. Admin Extensions run in Administration Console. Client Extensions are activated
through buttons on the Classic Contributor grid. For example, you configure an extension to print
Excel.
Using Contributor Applications
Cubes
Dimensions
e.Lists
A Contributor application is an Analyst plan that is made available to users on the Web through
the Contributor Administration Console. A Contributor application consists of a series of linked
cubes that can be used for data entry by many people at the same time.
A cube is similar to a spreadsheet. A cube always contains rows and columns and usually at least
one other page, making it multidimensional. It is used to collect data. Cells in cubes can contain
entered data or calculations.
The rows, columns, and pages of a cube are created from dimensions. Dimensions are lists of related
items, such as Profit and Loss items, products, customers, cost centers, and months. Dimensions
also contain all the calculations. One dimension can be used by many cubes.
The structure of an application is based on an e.List. An e.List is a kind of dimension that contains
a hierarchical structure that typically reflects the structure of the organization. For example, it may
Administration Guide 21

Chapter 2: IBM Cognos 8 Planning - Contributor
include cost centers and profit centers. There is one e.List per application, and the e.List item is
assigned to a user, group, or role. There are two types of user: planners and reviewers. A planner
enters and submits data to be reviewed by a reviewer. There may be several layers of reviewer
depending on the structure of the e.List.
Access Tables and Saved Selections
D-Links
Access to cubes is managed by e.List item, using saved selections and access tables. A saved selection
is a collection of dimension items that is assigned to e.List items using access tables. This means
that users can view only data that is relevant to them. For example, you may want to show only
travel expense items to one user and entertainment expense items to another user where both items
are held in the same dimension.
Using access tables, you assign different levels of access to e.List items, saved selections, dimension
items and cubes.
For more information, see "Managing User Access to Data" (p. 115).
Cubes are linked by a series of D-Links in Analyst. A D-Link copies information in and out of
cubes, and sometimes to and from ASCII or text files.
Managing Contributor Applications
There is a single configuration process for all Contributor applications in an installation.
You can use application folders to organize your applications into related groups. When you have
created them, you can use the application folders to assign job servers, job server clusters and access
rights to these groups of applications.
Multiple Administrators
Moving Data
22 Contributor
You can secure individual elements of the Administration Console and therefore allow multiple
administrators to access different parts of the Contributor application at the same time. For example,
you can give rights to a specific user to create and configure applications on a specific datastore.
You can choose to cascade rights to all applications on a datastore, or restrict rights to specific
applications. Contributor administrators have access only to those applications and operations that
they have rights for.
Administrators can use administration links to move data quickly and easily between applications
without having to publish, reducing the need for large applications. You can have several small,
focused applications. Smaller e.List structures provide quicker reconciliation times. Also, the need
for cut-down models and access tables is reduced.
Administration links give you the following benefits:
● You can achieve a matrix e.List structure.

System Links
For example, you can have a Company model where Human Resources reports into Country,
and this can be linked to a Corporate model where Country reports into Human Resources.
● You can import data from IBM Cognos 8 data sources.
using administration links, you can import data into IBM Cognos 8 Planning from packages
that were modeled and published in Framework Manager.
Administrators can set up links so that Web client users and Contributor for Excel users can move
data between Contributor cubes in the same or different applications. System links are run from
the target application.
Automating Contributor Tasks Using Macros
Publishing Data
You can group related tasks into a single macro to run them in sequence. For example, you can
group the following tasks: Load Import Data, Prepare Import, and Go to Production. Macros can
be run in the Administration Console, from IBM Cognos Connection, used in events created in
Event Studio, or by using external scheduling tools.
Three publish layouts are available.
The table-only layout is designed to give users greater flexibility in reporting on IBM Cognos 8
Planning data, and for use as a data source for other applications. It is used with the Generate
Framework Manager Model extension, and the Generate Transformer Model extension.
The incremental publish layout publishes only e.List items that contain changed data. Users can
schedule an incremental publish using a macro or through IBM Cognos Connection and Event
Studio. You can achieve near real-time publishing by closely scheduling incremental publishes.
The view layout, as supported in Contributor and Analyst version 7.2, is compatible with previous
IBM Cognos Planning data solutions.
Data is always published to a separate publish datastore.
Creating a Contributor Application
Creating a Contributor Application involves
❑ developing the plan in Analyst
❑ designing the e.List
❑ configuring rights
❑ creating the application
❑ creating the production application
❑ running jobs
Chapter 2: IBM Cognos 8 Planning - Contributor
Administration Guide 23

Chapter 2: IBM Cognos 8 Planning - Contributor
❑ testing the application in the Web site
Developing the Plan in Analyst
Designing the e.List
Assigning Rights
Create a business model for planning, budgeting, and forecasting using Analyst. This step is typically
performed by Analyst Model Builders.
You can specifically design the Analyst model to be optimized for Contributor (p. 337). Part of the
model development process involves establishing how the Contributor application is to be used in
the organization. This includes looking at who contributes data and reviews data. This information
is used to create an e.List.
For more information, see the Analyst User Guide.
An e.List is a very important part of the Contributor application. It specifies how the application
is distributed to end users, the hierarchy of the application, and security.
An e.List has a hierarchical structure that typically reflects the structure of an organization. The
dimension that represents the e.List is created in Analyst. The file containing e.List data is imported
into the Contributor Administration Console.
For more information, see "The e.List" (p. 93).
Rights determine whether users can view, save, submit, and so on.
For example, you want to allow a planner to view, but not save or submit, or to make and save
changes but not submit.
The rights a user can have are also affected by the view and review depth, set in the e.List window,
and the Reviewer edit setting in the Application Options window. A user can be directly assigned
rights, or inherited rights.
You can set up rights directly in the Administration Console after you create the Contributor
application, or you can create and maintain the rights in an external system, and import them.
For more information, see "The e.List" (p. 93).
Creating the Application
24 Contributor
After the model is created and tested in Analyst, create the Contributor application using the
Administration Console. The application creation wizard helps you create a Contributor application.
After the application is created, you can
● configure the application
This establishes how the application appears and behaves in the Web browser.
● import the e.List data and rights
● restrict what users can see and do using saved selections and access tables.

For example, you may want to hide salary details from some users.
● import data from other applications
After you set up the application, run the Production process.
Creating the Production Application
Running Jobs
There can be two versions of a Contributor application: development and production.
When you run the Go to Production process (p. 243), the development application becomes the
production application. The previous production application, if it existed, is archived and a new
development application is established. At this stage, the current production application and the
new development application are the same.
The production version is the live version of the application. It is the application that is online and
that users are working on.
Having two versions of an application means that you can make changes to the application without
having to take it offline, reducing the time that users are offline for as little as a minute. This is the
time taken to integrate the new e.List items into the hierarchy and set the correct workflow states
(p. 295).
Run the Go to Production process to formally commit a set of changes. When the Go to Production
process is complete, jobs run to ensure that all the data is up to date using a process named recon-
ciliation (p. 54). Reconciliation happens on the server side or, if the user tries to view or edit the
application before the e.List item is processed, reconciliation may happen on the client.
A job is an administration task that runs on job servers and is monitored by the Administration
Console. You can start the process and monitor its progress. All jobs can be run while the application
is online.
Testing the Web Site
The Administrator
Using the Monitoring Console (p. 61) in the Administration tree, you can manage and monitor the
progress of jobs in Contributor applications.
An example of a job is reconcile, which ensures that the structure of the e.List item data is up to
date, if required. This job is created and runs after Go to Production runs.
For more information, see "Jobs" (p. 49).
Chapter 2: IBM Cognos 8 Planning - Contributor
To test the Web site, run Go to Production and log on as a user with rights to the Contributor
application. You should be able to view the application in a web browser.
Administration can be divided into separate functions depending on your business needs. A Planning
Rights Administrator assigns administrative access to Contributor applications and to functions
within applications. Administrators have access only to those applications and operations that they
Administration Guide 25

Chapter 2: IBM Cognos 8 Planning - Contributor
The Planner
have rights for. In addition, multiple administrators can access different parts of the Contributor
application at the same time.
You can restrict administrative access on a per application basis so that someone who can see only
database maintenance in application A can create applications in application B.
Administrators see only those applications that they have rights to, and only those functions within
those applications.
Depending on the rights assigned to them, administrators can
● assign functional rights to other administrators
● add job servers and job server clusters to the Planning Store
● create and configure a Contributor application
● create new e.List items
● make changes to the e.list hierarchy
● assign rights to e.List items
● import actual data to the application
● amend workflow states from the Administration Console where required
● monitor the progress of jobs
Planners are responsible for entering data into the Contributor application using the web client, or
Contributor for Excel. This data is referred to as a contribution. Planners edit data only in the
selection assigned to them by the administrator. They cannot make structural changes to the
application. After data is entered, the planner can either save or submit the data. Submitted data
is forwarded to a reviewer and cannot be edited further by the planner unless the reviewer rejects
it.
The Reviewer
26 Contributor
A planner can be responsible for more than one e.List item and can view each e.List item individually
or view all e.List items in a single view, if configured by the administrator.
Reviewers are responsible for approving contributions submitted by one or more planners.
Reviewers can view data and see the status of all submissions they are responsible for managing at
any stage in the planning and review cycle. Reviewers can edit contributions if they have appropriate
rights.
After data is submitted, the reviewer has the following options:
● reject the data if they are not satisfied with it
Typically, a reviewer sends an email to the planner to give the reason for rejection.
● accept the data

The Toolbar
When a complete set of data is viewed and considered satisfactory, it can be submitted to the
next reviewer in the e.List hierarchy.
● edit the data, if allowed
After the reviewer takes over editorial control of a contribution, the planner is no longer the owner
of the contribution. The reviewer has the right to submit it.
Any user can be both a planner and a reviewer for the same e.List item. When users have both roles,
they can view their review items and contribution items in the same Web page.
In addition, reviewers can annotate any changes they make to a Contribution e.List item (p. 289).
The following functions are available on the Administration Console toolbar.
Icon
Action
Email
Save
Help
Go to Production
Set Online
Set Offline
Reset
Description
Sends e-mail to users defined in an application using your
default email tool.
Saves changes to the development application package.
Shows the Contributor Administration online help. You can
also use the F1 key.
Starts the Go to Production process. Go to production can be
automated.
Makes the application visible in a Web browser. Set Online
can be automated.
Prevents the application from being accessed in a Web browser.
Set Offline can be automated
Resets the development application to the production applica-
tion, clearing any changes that were made since you last ran
Go to Production.
Chapter 2: IBM Cognos 8 Planning - Contributor
Administration Guide 27

Chapter 2: IBM Cognos 8 Planning - Contributor
28 Contributor

Chapter 3: Security
IBM Cognos 8 security is designed to meet the need for security in various situations. You can use
it in everything from a proof of concept application where security is rarely enabled to a large scale
enterprise deployment.
The security model can be easily integrated with the existing security infrastructure in your organ-
ization. It is built on top of one or more other authentication providers. You use the providers to
define and maintain users, groups, and roles, and to control the authentication process. Each
authentication provider known to IBM Cognos 8 is referred to as a namespace.
In addition to the namespaces that represent other authentication providers, IBM Cognos 8 has its
own namespace named Cognos. The Cognos namespace makes it easier to manage security policies
and deploy applications.
For more information, see the IBM Cognos 8 Security and Administration Guide.
Cognos Namespace
The Cognos namespace is the IBM Cognos 8 built-in namespace. It contains the IBM Cognos
objects, such as groups, roles, data sources, distribution lists, and contacts.
During the content store initialization, built-in and predefined security entries are created in this
namespace. You must modify the initial security settings for those entries and for the IBM Cognos
namespace immediately after installing and configuring IBM Cognos 8.
You can rename the Cognos namespace using IBM Cognos Configuration, but you cannot delete
it. The namespace is always active.
When you set security in IBM Cognos 8, you may want to use the Cognos namespace to create
groups and roles that are specific to IBM Cognos 8. In this namespace, you can also create security
policies that indirectly reference other security entries so that IBM Cognos 8 can be more easily
deployed from one installation to another.
The Cognos namespace always exists in IBM Cognos 8, but the use of the groups and roles it contains
is optional. The groups and roles created in the Cognos namespace repackage the users, groups,
and roles that exist in the authentication providers to optimize their use in the IBM Cognos 8
environment. For example, in the Cognos namespace, you can create a group named HR Managers
and add to it specific users and groups from your corporate IT and HR organizations defined in
your authentication provider. Later, you can set access permissions for the HR Managers group to
entries in IBM Cognos 8.
Authentication Providers
User authentication in IBM Cognos 8 is managed by authentication providers. Authentication
providers define users, groups, and roles used for authentication. User names, IDs, passwords,
regional settings, personal preferences are some examples of information stored in the providers.
Administration Guide 29

Chapter 3: Security
30 Contributor
If you set up authentication for IBM Cognos 8, users must provide valid credentials, such as user
ID and password, at logon time. In IBM Cognos 8 environment, authentication providers are also
referred to as namespaces, and they are represented by namespace entries in the user interface.
IBM Cognos 8 does not replicate the users, groups, and roles defined in your authentication provider.
However, you can reference them in IBM Cognos 8 when you set access permissions to reports and
other content. They can also become members of Cognos groups and roles.
The following authentication providers are supported in this release:
● Active Directory Server
● IBM Cognos Series 7
● eTrust SiteMinder
● LDAP
● NTLM
● SAP
You configure authentication providers using IBM Cognos Configuration. For more information,
see the Installation and Configuration Guide.
Multiple Namespaces
If multiple namespaces are configured for your system, at the start of a session you must select one
namespace that you want to use. However, this does not prevent you from logging on to other
namespaces later in the session. For example, if you set access permissions, you may want to reference
entries from different namespaces. To log on to a different namespace, you do not have to log out
of the namespace you are currently using. You can be logged on to multiple namespaces simultan-
eously.
Your primary logon is the namespace and the credentials that you use to log on at the beginning
of the session. The namespaces that you log on to later in the session and the credentials that you
use become your secondary logons.
When you delete one of the namespaces, you can log on using another namespace. If you delete all
namespaces except for the Cognos namespace, you are not prompted to log on. If anonymous access
is enabled, you are automatically logged on as an anonymous user. If anonymous access is not
enabled, you cannot access the IBM Cognos Connection logon page. In this situation, use IBM
Cognos Configuration to enable anonymous access.
Hiding Namespaces
You can hide namespaces from users during logon. This lets you have trusted signon namespaces
without showing them on the namespace selection list that is presented when users log on.
For example, you may want to integrate single signon across systems, but maintain the ability for
customers to authenticate directly to IBM Cognos 8 without being prompted to choose a namespace.
You can hide Custom Java Provider and eTrust SiteMinder namespaces that you configured.
For more information, see the Installation and Configuration Guide.

Deleting or Restoring Unconfigured Namespaces
You can preserve namespaces and all their contents in the content store even if they are no longer
configured for use in IBM Cognos 8. When a namespace is not configured, it is listed as inactive in
the directory tool.
An inactive namespace is one that was configured, but later deleted in IBM Cognos Configuration.
The namespace can be deleted from the content store by members of the System Administrators
role. You cannot log on to an inactive namespace.
If a new version of IBM Cognos 8 detects a previously configured namespace that is no longer used,
the namespace appears in the directory tool as inactive. You can configure the namespace again if
you still require the data. If the namespace is not required, you can delete it.
When you delete a namespace, you also delete all entries in My Folders that are associated with
that namespace, and their contents.
An active namespace cannot be deleted, but can be updated.
To recreate a namespace in IBM Cognos Configuration, you must use the original ID of the
namespace. For information about configuring and recreating namespaces, see the Installation and
Configuration Guide.
Delete an Inactive Namespace
If a namespace was removed from IBM Cognos Configuration and is no longer required, a member
of the System Administrators role can delete it permanently in the directory tool. Deleting a
namespace also deletes all the entries in My Folders that are associated with the namespace.
To access the directory administration tool, you must have execute permissions for the directory
secured feature and traverse permissions for the administration secured function.
Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administra-
tion.
2. On the Security tab, click Users, Groups, and Roles.
If the namespace you want to delete does not have a check mark in the Active column, it is
inactive and can be deleted.
3. In the Actions column, click the delete button.
If the namespace is active, the delete button is not available.
The namespace is permanently deleted. To use the namespace again in IBM Cognos 8, you must
add it using IBM Cognos Configuration.
Users, Groups, and Roles
Chapter 3: Security
Users, groups, and roles are created for authentication and authorization purposes. In IBM Cognos 8,
you can use users, groups, and roles created in other authentication providers, and groups and roles
Administration Guide 31

Chapter 3: Security
Users
Groups and Roles
32 Contributor
created in IBM Cognos 8. The groups and roles created in IBM Cognos 8 are referred to as IBM
Cognos groups and IBM Cognos roles.
A user entry is created and maintained in other authentication providers to uniquely identify a
human or a computer account. You cannot create user entries in IBM Cognos 8.
Information about users, such as first and last names, passwords, IDs, locales, and email addresses,
is stored in the authentication providers. However, this may not be all the information required by
IBM Cognos 8. For example, it does not specify the location of the users' personal folders, or format
preferences for viewing reports. This additional information about users is stored in IBM Cognos 8,
but when addressed in IBM Cognos 8, the information appears as part of the external namespace.
Access Permissions for Users
Users must have at least traverse permissions for the parent entries of the entries they want to access.
The parent entries include container objects such as folders, packages, groups, roles, and namespaces.
Permissions for users are based on permissions set for individual user accounts and for the
namespaces, groups, and roles to which the users belong. Permissions are also affected by the
membership and ownership properties of the entry.
IBM Cognos 8 supports combined access permissions. When users who belong to more than one
group log on, they have the combined permissions of all the groups to which they belong. This is
important to remember, especially when you are denying access.
Tip: To ensure that a user or group can run reports from a package, but not open the package in
an IBM Cognos studio, grant the user or group execute and traverse permissions on the package.
Users can become members of groups and roles defined in other authentication providers, and
groups and roles defined in IBM Cognos 8. A user can belong to one or more groups or roles. If
users are members of more than one group, their access permissions are merged.
Groups and roles represent collections of users that perform similar functions, or have a similar
status in an organization. Examples of groups are Employees, Developers, or Sales Personnel.
Members of groups can be users and other groups. When users log on, they cannot select a group
they want to use for a session. They always log on with all the permissions associated with the
groups to which they belong.
Roles in IBM Cognos 8 have a similar function as groups. Members of roles can be users,
groups, and other roles.
The following diagram shows the structure of groups and roles.

User
Group
Role
Group User
Group Role
You create IBM Cognos groups and roles when
● you cannot create groups or roles in your authentication provider
● groups or roles are required that span multiple namespaces
● portable groups and roles that can be deployed are required
In this case, it is best to populate groups and roles in the other provider, and then add those
groups and roles to the IBM Cognos groups and roles to which they belong. Otherwise, you
may have trouble managing large lists of users in a group in the Cognos namespace.
● you want to address specific needs of IBM Cognos 8 administration
● you want to avoid cluttering your organization security systems with information used only in
IBM Cognos 8
IBM Cognos 8 Planning Roles
Capabilities
There are two predefined roles for IBM Cognos 8 Planning:
● Planning Rights Administrators
This role enables you to access Contributor Administration Console, Analyst, and all associated
objects in the application for the first time following installation. You can then change the
roles, groups, and users who can access the Contributor Administration Console and to Analyst.
● Planning Contributor Users
This is the default role for users who want to access the Contributor Web client, Contributor
for Excel, or Analyst. However, anyone can be assigned rights to use the Contributor Web
client, or Contributor for Excel regardless of whether they are a member of the Planning Con-
tributor Users role. Analyst users must be members of the Planning Contributor User role.
Note: You do not have to use these roles, they can be deleted or renamed. If you decide not to use
the predefined roles, you must assign the access permissions and capabilities required by IBM
Cognos 8 Planning to other groups, roles, or users.
Capabilities are secured functions and features. If you are an administrator, you set access to the
secured functions and features by granting execute permissions for specified users, groups, or roles.
Users must have at least one capability to be accepted through the IBM Cognos Application Firewall.
The Planning Contributor Users role has the Planning Contributor capability by default. If you do
not want to use this role, you can assign the capability to any groups, users, or roles that you create
to replace this role by giving execute permissions to the appropriate members.
Chapter 3: Security
Administration Guide 33

Chapter 3: Security
The Planning Rights Administrators role has the Planning Rights Administration capability by
default. To assign this capability to groups, users, or roles, you must give execute permissions to
the appropriate members. You must also give members permissions to traverse the Administration
folder.
Tip: You change capabilities through IBM Cognos Administration, by clicking the Security tab.
For more information, see "Securing Functions and Features" in the Administration and Security
Guide.
Capabilities Needed to Create IBM Cognos 8 Planning Packages
You can create a Planning Package during the Go to Production process, giving users access to IBM
Cognos 8 studios from the Contributor application and enabling users to report against live Con-
tributor data using the Planning Data Service. To do this, the Planning Rights Administrators role
must be granted the Directory capability. Members of the System Administrator role are automat-
ically granted this capability, but Planning Rights Administrator members are not.
Setting up Security for an IBM Cognos 8 Planning Installation
34 Contributor
You must set up security for an IBM Cognos 8 Planning installation.
To configure security for IBM Cognos 8 Planning, do the following:
❑ Using Cognos Configuration, configure IBM Cognos 8 to use an authentication provider
❑ Using IBM Cognos Administration
● add Contributor Administration Console and Analyst administrators to the Planning Rights
Administrators role
● add Contributor application members and Analyst users to the Planning Contributor Users
role
● enable Planning Roles in IBM Cognos 8
● restrict access to the everyone group
● create additional roles or groups for IBM Cognos 8 Planning (optional)
Note: We recommend that you add groups of users as defined in your authentication pro-
vider to the roles in IBM Cognos 8 Planning, rather than individual users. This means that
changes in group membership are reflected immediately in the roles without having to make
changes in IBM Cognos 8
❑ To configure Analyst security:
● configure integrated Windows authentication if you want to execute macros without
interaction
● specify a default library
● assign access at object, library, or item level
❑ Using the Contributor Administration Console

● set access rights for Contributor administrators to Contributor administration functions
● set rights for Contributor application users for Contributor applications
Configure IBM Cognos 8 to Use an Authentication Provider
IBM Cognos 8 components can run with two types of access: anonymous and authenticated. By
default, anonymous access is enabled. To use IBM Cognos 8 Planning, you must disable anonymous
access so that users are required to log on. Only authenticated users can access your Planning
applications.
For authenticated access, you must configure IBM Cognos 8 components to use a namespace
associated with an authentication provider used by your organization. You can also configure
multiple namespaces. At run time, users can choose which namespace they want to use.
Note: If you are using the Generate Transformer Model extension, you must add the IBM Cognos
Series 7 namespace. Local authentication export (LAE) files cannot be used.
Steps to Disable Anonymous Access
1. On each Content Manager computer, start IBM Cognos Configuration.
2. In the Explorer window, under Security, Authentication, click IBM Cognos.
The IBM Cognos resource represents the Cognos namespace. For more information, see the
Administration and Security Guide.
3. In the Properties window, ensure that Allow Anonymous Access is set to False.
4. From the File menu, click Save.
Steps to Configure Authentication Providers
1. On each Content Manager computer, start IBM Cognos Configuration.
2. In the Explorer window, under Security, right-click Authentication, and then click New resource,
Namespace.
3. In the Name box, type a name for your authentication namespace.
4. In the Type list, click the appropriate namespace and then click OK.
The new authentication provider resource appears in the Explorer window, under the
Authentication component.
5. In the Properties window, for the Namespace ID property, specify a unique identifier for the
namespace.
6. In the Properties window for Authentication, for the Allow session information to be shared
between client applications, set the value to True.
This enables you to have single signon between multiple clients on the same computer. Note
that you cannot have single signon between a Windows application, and a Web client application,
for example, Contributor administration and IBM Cognos 8.
Chapter 3: Security
Administration Guide 35

Chapter 3: Security
7. Specify the values for all other required properties to ensure that IBM Cognos 8 components
can locate and use your existing authentication provider.
8. Test the connection to a new namespace. In the Explorer window, under Authentication, right-
click the new authentication resource and click Test.
9. From the File menu, click Save.
IBM Cognos 8 loads, initializes, and configures the provider libraries for the namespace.
For more specific information regarding the configurion of each kind of authentication provider,
see the IBM Cognos 8 Planning Installation and Configuration Guide.
Add or Remove Members From Planning Rights Administrators and Planning
Contributor Users Roles
36 Contributor
Using IBM Cognos Administration, add Contributor Administration Console administrators and
Analyst administrators to the Planning Rights Administrators role. Add Contributor application
and Analyst users to the Planning Contributor Users role.
Steps
1. In IBM Cognos Connection, in the upper-right corner, click IBM Cognos Administration.
2. On the Security tab, click Users, Groups, and Roles.
3. Click on the IBM Cognos namespace.
4. In the Actions column, click the properties button for the Planning Rights Administrators or
Planning Contributor Users role.
5. Click the Members tab.
6. To add members, click Add and do the following:
● To choose from listed entries, click the appropriate namespace.
● To search for entries, click the appropriate namespace and then click Search. In the Search
string box, type the phrase you want to search for. For search options, click Edit. Find and
click the entry you want.
● To type the name of entries you want to add, click Type and type the names of groups,
roles, or users using the following format, where a semicolon (;) separates each entry:
namespace/group_name;namespace/role_name;namespace/user_name;
Here is an example:
Cognos/Authors;LDAP/scarter;
7. Click the right-arrow button, and when the entries you want appear in the Selected entries box,
click OK.
Tip: To remove entries from the Selected entries list, select them and click Remove. To select
all entries in a list, click the check box in the upper-left corner of the list. To make the user
entries visible, click Show users in the list.

8. Click OK.
For more information, see the IBM Cognos 8 Administration and Security Guide.
Enabling Planning Roles in IBM Cognos 8
Planning tasks that require access to the IBM Cognos 8 data store, such as running macros, go to
production, and adding job servers, require additional security configuration. Access to the data
store is restricted to certain groups through IBM Cognos Administration. You must have a system
administrator or a user from one of the following groups perform tasks that require the IBM
Cognos 8 data store. Optionally, you can add users to the required groups to perform the tasks.
Group
Data Manager
Authors
Directory Adminis-
trators
Report Administrat-
ors or Server Admin-
istrators
Tool and Task
Framework Manager
Only members of the Data Manager Authors group can import from a
Framework Manager data source.
Restricting Access to the Everyone Group
You must have a Data Manager Authors group member perform this task.
IBM Cognos Administration Configuration, Data Source Connections
You must have a Directory Administrator create a data source named IBM
Cognos Planning - Contributor with a connection of type IBM Cognos
Planning - Contributor before performing go to production.
IBM Cognos Administration Configuration, Content Administration
A Report Administrators or Server Administrators group member must
publish and run macros in Content Administration.
The Everyone group represents all authenticated users and the Anonymous user account. The
membership of this group is maintained by the product and cannot be viewed or altered.
By default, the Everyone group belongs to several built-in groups and roles in the Cognos namespace.
To restrict access, remove the Everyone group the System Administrators role and replace it with
authorized groups, roles, or users. Optionally, remove the Everyone group from the Planning
Contributor Users role to restrict access to Contributor plans.
For more information about the Everyone group, and System Administrators role, see "Initial
Security" in the Administration and Security Guide.
Recommendation - Creating Additional Roles or Groups for Contributor
To secure your Contributor applications, you may want to create roles or groups for the following
users:
● Classic Contributor client extensions
Chapter 3: Security
Administration Guide 37

Chapter 3: Security
● Contributor work offline users
for example, create one work offline role per Contributor application and assign the offline
users to the relevant role. The application administrator must also belong to this role.
● system links
● translated applications
Planning Contributor User Roles
When you assign user rights to Contributor applications, the first time you click User, Group, Role
in the Rights window, a list of all the Users, Groups, and Roles that are members of the Planning
Contributor Users role is displayed. If the Planning Contributor Users role contains a large number
of members directly below, you can improve performance by creating a smaller number of groups
or roles below the Planning Contributor Users role to act as filters.
Note: Members of roles can be users, groups, and other roles. Groups can contain users and other
groups, but not roles.
Planning Rights Administrator Roles
If you have a large number of administrators, you may wish to create a roles, or groups for specific
tasks, and then add the individual users to this role or group. For example, a role Allow System
Links can be used for this task, and any user added to that role is assigned that right.
For more information about creating groups or roles, see the Administration and Security Guide.
Configuring Access to the Contributor Administration Console
38 Contributor
Administrative access can be set for the IBM Cognos 8 Planning environment or the datastore server
that it contains. It can also be set for the application or publish container objects in the datastore
server, the job server objects in the job server cluster, links, and macros. You can also set rights to
individual functions of these objects.
If you are an administrator with no access rights to an object, you cannot view the details for that
object in the Administration Console, and cannot select these objects. You will see the datastore
servers, even if you have no rights to it, because you may have rights to applications on the datastore
server. If you have no rights to any object, the Contributor Administration Console closes.
Cascade Rights
If you set rights to operations for the IBM Cognos 8 Planning environment, the datastore server,
or the job server, you are prompted to cascade the rights to the lower levels. Regardless of your
response, when you grant rights to a datastore server or job server cluster, the user automatically
inherits the same rights for any applications, publish containers, or job servers that you subsequently
add.
Tip: To always cascade rights without being prompted, in the Access Rights window, click Cascade
rights selection.
Rights that are cascaded are indicated by blue text.

Operations are the functions that can be performed in the Contributor Administration Console.
Initially, a Planning Rights Administrator grants rights so that other Contributor administrators
perform these operations.
Granting Access Rights to Administrators
You can grant rights so that administrators can view who has write access to the development
model, select an application and cube as the source and target of a system or administration link,
add or remove a datastore server, and add a job server cluster.
Rights
Session Details Access
Global Administration
Privileges
You can grant the write to view who has write access to the
development model.
You can grant the right to
Access ● run Go to Production to create the production application
Links Access
Datastores Access
● modify the datastore connection details for applications and
publish containers
● set an application online or offline in the Web client
● assign access rights
You can assign access rights to datastores, applications, publish
containers, job server clusters, and job servers.
You can secure the ability to create, edit, execute, delete, import,
and export administration links. You can also secure previously
created administration links (administration link instances).
You secure Administration Link instances individually. To locate
them, scroll to the bottom of the Operations tree and look for
LinkLink Name.
You can grant the right to select an application and cube as the
source and target of a system or administration link.
Chapter 3: Security
You can grant the right to add or remove a datastore server.
Administration Guide 39

Chapter 3: Security
40 Contributor
Rights
Application Containers
Privileges
You can grant the right to
Access ● upgrade or import a Contributor application from an earlier
Publish Container Access
version of Contributor
● link to an existing application
● create an application
● create a script that can be run by a database administrator to
create an application. This option is used when the Generate
Scripts option is set to Yes in the Admin Options table
● remove an application from the Planning environment
● assign or remove an application from an application folder
You can grant rights for administering publish containers
● link to a publish container
● create a publish container
● create a script that is run by a database administrator to create
a publish container.
This option is used when the Generate Scripts option is set to
Yes in the Admin Options table.
Publish containers are created the first time someone publishes.
The administrator must have the right to create a publish container
in order to publish.
For publish jobs to be processed, the publish container must be
added to a job server cluster or job server.
To modify a publish datastore connection you must have the
Global Administration right Modify connection document.

Rights
Development Access
Production Access
Job Server Clusters Access
Job Server Access
Steps
1. Click Access Rights.
2. Click Add.
Privileges
You can grant the right to perform the following operations in a
development application
● configure the Web client - navigation, orientation, options,
planner-only cubes and Contributor help
● configure application maintenance options
● import and maintain the e.List, and rights
● create and maintain access tables and saved selections
● import data
● synchronize
● set datastore options
● create and maintain translations
You can grant the right to perform the following operations on
the production version of the application
● publish data
● delete annotations
● preview data
This option is important if you want to hide sensitive data
● manage extensions
You can grant the right to add or remove a job server cluster.
You can grant the right to update job server properties for the
Planning environment.
Go to a Job server cluster
● to enable and disable job processing of an application
● to add and remove job servers from a job server cluster
● to add and remove applications, and publish containers from
the job server
● to update job server properties
Chapter 3: Security
Administration Guide 41

Chapter 3: Security
3. Click the appropriate Namespace and select the user, group, or role.
4. Click the green arrow button and then click OK.
5. Under Name, select the name.
6. Click the operations needed.
Tip: you can filter operations by datastore, application, publish container, job server cluster,
and job server.
7. Click Save.
Access Rights for Macros
42 Contributor
Access rights apply as soon as the changes are saved.
A macro consists of one or more macro steps that you select when you create a macro. For example,
a macro that imports data into a cube, named "Import Expenses", might contain the following
macro steps:
● Upload an Import File
● Prepare Import
● Go To Production
You can secure the rights to create, edit, execute, delete, and transfer macros, and the ability to
create individual macro steps.
By default, when a user with the Create Macro right adds a new macro instance, they are granted
all rights to it - edit, execute, delete and transfer. For other users, the access to that instance are
determined by their rights.
After a link or macro is created, only a Planning Rights Administrator can change the instance
rights.
For example, consider a user who is granted create, edit, and execute macro access rights. By default,
this user has all access rights to macros they create. However, they only have edit and execute rights
to those created by other users. A Planning Rights Administrator can subsequently grant or revoke
any rights to those macros for any user.
The Execute Command Line macro step is secured by default. This is to minimize the risk of
unauthorized access to resources.
You can also secure the rights to edit, execute, delete and transfer previously created macro instances,
for example, "Import Expenses".
Rights Needed to Transfer Macros
Transferring a macro enables you to copy steps from one macro to another, add steps to another
macro, and make a copy of an existing macro. To do this, you must have:
● transfer rights for the macro instance being transferred to or from
● edit rights for the target macro

● create macro step rights for all the macro steps that you are transferring
Authentication of Macros
Authentication is based on the security context under which the macros are run. For example, if
the macro contains a Go to Production step, the user specified in the authentication details when
you create a macro must have the rights to run Go to Production. This is separate from the access
rights used to secure the management of macros.
Recommendation - Granting Rights
We recommend that you secure the "Execute Command Line" step to prevent unauthorized access
to the functionality that you can execute from the commend line.
Grant the create macro step "Execute Command Line" rights to trusted users only, typically Planning
Rights Administrators who can schedule macros on the Contributor server.
Revoke edit, transfer, and delete rights from all macro instances that contain the "Execute Command
Line" step to prevent unauthorized change by another user. An administrator would have to re-
grant edit, transfer, and delete rights to permit any kind of maintenance changes to the macro.
Set Access Rights for Contributor Macros in IBM Cognos Connection
Contributor macros that are published to IBM Cognos Connection must be secured by the Planning
Rights Administrator or the System Administrator to ensure that only the required users, groups,
and role have access to execute or schedule macros.
You must be a member of the Planning Rights Administrators or System Administrator roles to
change user, group, and role capabilities.
Steps
1. In IBM Cognos Connection, in the upper-right corner, click IBM Cognos Administration.
2. On the Security tab, click Capabilities.
3. Click the actions button next to the Administration capability and click Set Properties button
. On the Permissions tab, grant the traverse permission to the required users, groups, and
roles and click OK.
4. Click the Administrator capability to show additional functions. Click the actions button next
to Run activities and schedules and click Set Properties. On the Permissions tab, grant execute
and traverse permissions to the required users, groups, and roles and click OK.
5. On the Configuration tab, click Content Administration.
6. Click the Set Properties button on the Administration page. On the Permissions tab, grant
read, execute, and traverse permissions to the required users, groups, and roles.
If required, grant write permission if you want the user, group, or role to be able to modify the
contents of this folder. Grant set policy permission if you want the user, group, or role to be
able to change security permissions on this folder.
7. Click OK.
Chapter 3: Security
Administration Guide 43

Chapter 3: Security
Members of the required users, groups, or roles now have access schedule and run Contributor
macros in IBM Cognos Connection.
Assign Scheduler Credentials
44 Contributor
All scheduled macros, and some jobs, run under the identity setup in the IBM Cognos scheduler or
the scheduler credentials for other schedulers. This is because macros and jobs that run in the
background cannot prompt the user for authentication information. Scheduler credentials are also
used to lookup Contributor email addresses from workflow pages.
Scheduler credentials are associated with an authenticated user, which can include more than one
user logged on to different namespaces. The user, or group or role that they are a member of, must
have rights granted in the Access Rights window to run macros, jobs, and lookup email addresses.
If there are users from multiple namespaces in your application, you must have scheduler credentials
associated with those namespaces. When the Validate Users job is run, the scheduler credentials
must be associated with all the namespaces you imported users from. If you are logged on to only
one namespace, users that belong to other namespaces are considered invalid.
Macros that are run directly from the Contributor Administration Console through user interaction
run under the currently logged on user account and do not use the scheduler credentials. Macros
that are triggered through events run under the identity used to create the event, not the scheduler
credentials.
Only users who have the Planning Rights Administrator capability can modify the scheduler creden-
tials. By default, the scheduler credentials are associated with the user who opens the Contributor
Administration Console for the first time, if that user is a Planning Rights Administrator. If that
user is not a Planning Rights Administrator, a message states that the credentials are invalid, or do
not exist, and a Planning Rights Administrator must update the scheduler credentials.
Note that the following Contributor jobs use the scheduler credentials:
● Validate Users
● Reconcile
Steps
1. In the Systems Settings pane, click the Scheduler Credentials tab, and click Update.
2. Click Logon.
Initially, the Logon As button is disabled.
3. Enter the User ID and password to be used as the scheduler credentials and click OK.
4. If your logon is successful, the Logon button is disabled, and the Logon as button is enabled.
This enables you to log on to different namespaces.
You must provide scheduler credentials for all namespaces that users of the applications are
imported from.

After you create and configure Contributor applications, the next step is to configure user access.
You do this by assigning users, roles, or groups to e.List items in the Rights window in the Contrib-
utor Administration Console, either by importing a file, or by manually inserting rights.
Chapter 3: Security
Administration Guide 45

Chapter 3: Security
46 Contributor

Chapter 4: Configuring the Administration Console
When you start the IBM Cognos 8 Planning - Contributor Administration Console for the first time
you must configure it before you can use it.
Before you can configure the IBM Cognos 8 Planning - Contributor Administration Console, you
must be a member of the Planning rights administration capability which by default, is granted to
members of the Planning rights administration role. The Planning rights administration capability
can be granted to any user, group, or role (p. 33).
To configure the IBM Cognos 8 Planning - Contributor Administration Console
❑ Create the Planning tables in the Planning content store (p. 47).
❑ Add a datastore server (p. 48).
❑ Add job server clusters and job servers (p. 56).
❑ Configure administration security for the Contributor Administration Console.
When you have completed these tasks, applications can be created, imported, or upgraded (p. 60).
Creating Planning Tables
The first time the Contributor Administration Console is run, a check is run to see if any Planning
tables exist in the Planning store. If not, you are prompted to create them.
You can either create the tables by selecting Create and populate tables now or you can choose to
create the tables using a script which is then run by a Database Administrator (DBA). Use this
option if you do not have access rights to create tables in the database. To choose the script option,
you select Generate table scripts and data files and enter the location of where to save the script.
The script is then created automatically and the DBA can run the script to create the tables.
If the filesys.ini was not specified during installation, you must specify the path when you create
Planning tables. You change this setting if the default path is not used.
If you want to work with a different FileSys.ini, and the associated properties and samples other
than the default, select the Allow use of non-default FileSys.ini check box.
The filesys.ini file is a control file used by Analyst. It contains file paths for the Libs.tab, Users.tab,
and Groups.tab that control the specific library and user setup. You can edit the filesys.ini path by
selecting Tools, Edit FileSys.Ini path.
Planning tables are typically prefixed with a P_, and hold information about
● datastore servers
● Contributor application datastores
● job servers and job server clusters
● security
Administration Guide 47

Chapter 4: Configuring the Administration Console
● macros
● administration links
● jobs
Add a Datastore Server
48 Contributor
When you open the Contributor Administration Console for the first time, you must add an
application datastore server.
Steps
1. Right-click Datastores in the Administration tree, and click Add Datastore.
Tip: You can also modify the existing application datastore connection by clicking the Configure
button on the Datastore server information page (p. 49).
2. Select the Datastore provider.
The options are SQL Server, Oracle or DB2.
3. Do one of the following:
● For SQL Server, enter the Datastore server name, or click the browse button to list the
available servers
● For Oracle, enter the service name.
● For DB2, enter the database name.
4. Enter the information as described in the table below:
Setting
Trusted Connection
Use this account
Password
Preview Connection
Description
Click to use Windows authentication as the method for
logging on the datastore. You do not have to specify a sep-
arate logon id or password. This method is common for
SQL Server datastores and less common, but possible, for
Oracle.
Enter the datastore account that this application will use to
connect. This box is not enabled if you use a trusted connec-
tion.
Type the password for the account. This box is not enabled
if you use a trusted connection.
Provides a summary of the datastore server connection
details.

Setting
Test Connection
Description
Mandatory. Click to check the validity of the connection
to the datastore server.
5. If you want to configure advanced settings, click Advanced.
Typically these settings should be left as the default. They may not be supported by all datastore
configurations.
Enter the following information.
Setting
Provider Driver
Connection Prefix
Connection Suffix
Datastore Server Information
Jobs
Types of Jobs
Description
Select the appropriate driver for your datastore.
Specify to customize the connection strings for the needs of
the datastore.
Specify to customize the connection strings for the needs of
the datastore.
When you click the datastore server name in the tree, the datastore server information is displayed.
The datastore server connection area displays the connection string that is used to connect to the
datastore server. You can configure the datastore connection, change the datastore server, change
the account detail and test the connections by clicking the Configure button.
A job is an administration task that runs on job servers and is monitored by the Administration
Console.
Additional servers can be added to manage applications, speeding up the processing of jobs. You
can run the job and monitor its progress. All jobs can be run while the application is online to Web
clients. This means that you can make changes to the development version of an application while
the production version is live. It reduces the offline time during the Go to Production process.
Each job is split into job items, one job item for each e.List item. If you are running a Publish job
for eight e.List items, eight job items are created. Contributor applications can be added to more
than one job server, or to a job server cluster. When a job is created, job items are run on the dif-
ferent job servers, speeding up the processing of a job.
The following table describes each type of job:
Chapter 4: Configuring the Administration Console
Administration Guide 49

Chapter 4: Configuring the Administration Console
Job Type
Commentary tidy
Cut-down models
Cut-down tidy
Export queue tidy
Import queue tidy
Inter-app links
Job test
Language tidy
Prepare import
Publish
Reconcile
Reporting publish
Validate links
Validate users
Run Order for Jobs
50 Contributor
Description
Deletes user annotations and audit annotations, and references to
attached documents (p. 290).
Cuts down applications (p. 138).
Removes any cut-down models that are no longer required.
Removes obsolete items from the export queue.
Removes from the import queue model import blocks that are no longer
required.
Transfers data between applications.
To run successfully, requires that links are reconciled to e.List items.
Test the Job sub system using a configurable Job Item.
Cleans up unwanted languages from the data store after the Go to Pro-
duction process is run. This job is created and runs after Go to Produc-
tion is run.
Processes import data ready for reconciliation (p. 176).
Publishes the data to a view format (p. 259).
Ensures that the structure of the e.List item data is up to date. This job
is created and runs after Go to Production is run. For more information,
see "Reconciliation" (p. 54).
Publishes the data to a table-only format (p. 265).
Updates the validation status of links.
Checks to see if the owner or editor of an e.List item has the rights to
access the e.List item. For more information, see "Ownership" (p. 95).
The job checks the rights of users and updates the information in the
Web browser. This job is created only if a change is made to the Con-
tributor model, and runs after Go to Production is run.
The order in which jobs are run depends on the number of job processors, the hardware used, and
the job polling interval. If there is one job processor, jobs are run in no specific order. If there is
more than one job processor, the first job processor to poll for a job picks a job in no specific order

and runs it. The additional job processors prioritize queued jobs over running jobs and pick one
of the queued jobs to work on in no specific order. If there are enough job processors, all jobs can
be run at the same time.
Because jobs are independent of each other, they do not need to run in a specific order. The
exception is the publish job. The publish job can be started when a reconcile is running, but for it
to complete successfully, all e.List items that are being published must be reconciled.
Actions That Cause Jobs to Run
Securing Jobs
The following actions in the Administration Console cause jobs to run.
Action
Import data (p. 143)
Running administration links
Publish data (p. 259)
Delete annotations (p. 290)
Create a new application
Cut-down model options
Change planner-only cubes
Synchronize with IBM Cognos 8 Planning -
Analyst
* Triggered by Go to Production
Job
prepare import and reconcile *
inter-app links, validate links
publish and reporting publish
annotations tidy
reconcile *
cut-down models and cut-down tidy *
reconcile *
reconcile *
Changes in the following areas do not cause jobs to be run:
● navigation
● orientation
● Contributor help text
● all application settings except for cut-down models
● the backup file location
Chapter 4: Configuring the Administration Console
Some jobs run under scheduler credentials. This is because jobs that run in the background cannot
prompt the user for authentication information. Scheduler credentials are associated with an
authenticated session, which can include more than one user logged on to different namespaces.
Administration Guide 51

Chapter 4: Configuring the Administration Console
Managing Jobs
52 Contributor
The following jobs run under scheduler credentials:
● Validate users
When the Validate users job is run, the scheduler credentials must be associated with all the
namespaces you imported users from. If it is logged on to only one namespace, users that belong
to other namespaces are considered invalid.
● Reconcile
● all jobs launched by a scheduled macro
Only members of the Planning rights administrator capability can modify the scheduler credentials.
For information about setting the scheduler credentials, see "Assign Scheduler Credentials" (p. 44).
You can manage and monitor the progress of running jobs in applications from the Job Management
branch in the Administration tree, or from the Monitoring Console (p. 61).
You can also monitor the progress of jobs triggered by administration links from the Monitor Links
window.
The Job Monitor shows the following information:
Details
Status
Succeeded
Failed
Total Items
Estimated Completion
Description
The status is one of the following:
● creating
● ready to run
● queued. The job is waiting to be run. The job may have to wait
for a job server to become available before it can be run.
● running
● complete - the job has finished running successfully
● cancelled - the job has failed and was cancelled. Double-click
on the line to find out more.
The number of job items that ran successfully. If all did, All is stated.
A percentage is shown.
The number of job items that failed, if any.
The total number of job items that the job is split into. Jobs are
broken down into atoms of work known as job items, enabling a
job such as Publish to be run over different threads.
An estimated date and time of completion for the job in local time.

Details
Average Duration
Next Item
Start
Last Completion
Duration (min)
Description
Description
The average interval between the completion of job items.
The next job item to be run.
The date and time when the job started, in the local format.
The time when the last job item was completed.
The time in minutes the job task has taken to complete.
A description of the job type.
The lower area shows tasks running on job servers.
Details
Status
Start
End
Duration (min)
User
Process ID
Thread ID
Description
Indicates when a job is running.
The date and time when the job started on that processor in local
format.
Job View Refresh Interval (seconds)
The date and time when the job stopped running on that processor.
The time in minutes the job task has taken to complete.
The user account on the job server.
The process ID can be used for debugging.
The thread ID can be used for debugging.
You can change the job view refresh interval to whatever you feel is appropriate. We recommend
that you do not set it to less than 5 seconds. For most people's needs, 15 seconds is adequate. If
network traffic is an issue, the interval can be longer.
Publish Jobs
The publish process is carried out by the reporting publish job for a table-only layout (p. 265), or
the publish job if a view layout (p. 279) is selected.
To monitor publish jobs in the jobs monitor, select the publish container from the box that is
available at the top of the job monitor.
Chapter 4: Configuring the Administration Console
Administration Guide 53

Chapter 4: Configuring the Administration Console
Cancelled Jobs
If a Job is cancelled, you can show information about why this happened by double-clicking on the
line.
Reconciliation
Pausing Jobs
If you want to pause a running job, you must stop the Job Server. To do this, right-click the job
server or job server cluster name and click Disable Job Processing.
Reconciliation ensures that the copy of the application that the user uses on the Web is up to date.
For example, all data is imported, new cubes are added, and changed cubes are updated.
Reconciliation takes place after Go to Production runs and a new production application is created.
It also takes place when an administration link or an Analyst to Contributor link to the production
application is run. However, in this case, only the imported data is updated. The application is
reconciled on the job server unless a user tries to access an e.List item before it is reconciled. For
more information, see "The Effect of Changes to the e.List on Reconciliation" (p. 104).
All contribution e.List items are reconciled and aggregated if
● the application was synchronized with Analyst
● changes were made to the Access Tables, Saved Selections, or the e.List that resulted in a different
pattern of No Data cells for contribution e.List items that are common to both the development
and production applications
Note: Changing an access setting to No data, saving the application, and then changing the
access setting to what it was previously also results in reconciliation.
● they have import blocks
Note: If you use the Prepare zero data option, an import data block is created for all e.List
items, so all e.List items are reconciled.
● children were added or removed
● they are new
Reconciliation on the Server
54 Contributor
During reconciliation on the server, the following process occurs for each e.List item:
● The data block is loaded onto the job server.
● The transformation process occurs
New cubes are added, changes are made to existing cubes such as dimensions added or removed,
and access tables are applied.
● Data is imported.
● Data is saved.

Reconciliation on the Client
Deleting Jobs
Reconciliation can be performed across multiple processors and job servers. For more information,
see "Manage a Job Server Cluster" (p. 56).
If a user attempts to open an e.List item that is not yet reconciled, the e.List item is reconciled on
the user's computer. This may take a few minutes.
In the Web application, the user can determine the state of an e.List item by the workflow icon. If
an icon is enclosed in a red box, the item is out of date and needs reconciling. For more information,
see "Workflow State Definition" (p. 295).
If the Prevent client-side reconciliation check box is selected (p. 82), a user cannot open the e.List
item until the e.List item is reconciled on the server side.
You can delete jobs, but we do not recommended it because it can leave your data in an unstable
state.
Tip: If you want to pause a running job, you can stop the job server. Right-click the name of the
job server or job server cluster and click Disable Job Processing.
Prepare import
If you delete a prepare import job, the next time you run Prepare import, it tidies this up.
Cut-down models
You typically delete a cut-down models job after you cancel the Go to Production process. Clicking
the Go to Production button reruns the cut-down models job. If you delete a cut-down models job
during Go to Production, Go to Production does not run.
Reconciliation
If you delete a reconcile job, all e.List items that were not reconciled stay unreconciled. e.List items
that were already reconciled by the job remain reconciled. When a user attempts to view an unre-
conciled e.List item in the grid, if client side reconciliation is allowed, the reconciliation process
takes place on the client. If client side reconciliation is not allowed, users cannot view the e.List
items. Rerun the Go to Production process to trigger a repair reconcile job.
Managing Job Servers
A job server cluster groups the job servers that are used to process administration jobs. You can
stop, start, and monitor all job servers in a cluster at the same time. You can also choose to have
specific objects run on individual servers.
When you create a Contributor application, you are prompted to choose a cluster or server to run
the jobs.
You can add applications and publish containers to multiple job servers. This speeds up the pro-
cessing of jobs, such as reconciliation, giving near linear improvements per processor.
The following two scenarios provide examples of how this might work.
Chapter 4: Configuring the Administration Console
Administration Guide 55

Chapter 4: Configuring the Administration Console
Scenario 1
If you publish large amounts of data, you might want to assign the publish container to different
servers than those that are processing the main application. This is because if you assigned the
application container and the publish container to cluster X containing servers A, B,C, D, it is
possible that a large job, for example, publishing 5000 e.List items, could consume all the resources
in cluster X for some time, preventing other jobs from being processed. So in this case you might
want to assign the publish container to, for example, servers A and B, and the application container
to server C and D to enable other jobs such as prepare import, and server-side reconciliation to run
at the same time as the publish job. There is no control at job level.
Scenario 2
If you have some applications that are in production and are live, you might want to have one or
more job clusters with your best hardware to monitor these applications to ensure that they are
stable and available. For applications that are in development, you might want to have a different
job cluster containing your less efficient hardware.
For more information, see "Jobs" (p. 49). You can also automate job server management (p. 199).
Manage a Job Server Cluster
Before administration jobs can be processed, you must add a job server cluster to the Administration
Console. A job server cluster manages a group of job servers. For information on managing job
servers, see "Managing Job Servers" (p. 55).
Steps
1. Right-click Job Server Clusters and click Add Job Server Cluster.
2. Type a unique name for the job server cluster.
3. Click Add.
The next step is to add job servers to the job server cluster.
4. Remove a job server cluster by right-clicking it and selecting Delete Job Server Cluster.
5. Disable job processing on a cluster by right-clicking the cluster and selecting Disable Job Pro-
cessing.
6. To test communication with the job server, right-click the job server name and click Test. Any
errors are displayed in a message box.
Add a Job Server and Change its Content Store
56 Contributor
You must add job servers to a job server cluster so that administration jobs can be processed.

Job servers can exist in only one Planning content store. You can either manually delete the job
server (p. 59) and add it to the new Planning content store, or on the job server, change the content
store that it is associated with.
Steps to Add a Job Server
1. Right-click Job Servers and click Add Job Server.
2. Select a job server from Available Servers.
Computers that are job servers must have the Planning job service option enabled in IBM
Cognos Configuration. For more information, see the IBM Cognos 8 Planning Installation and
Configuration Guide.
3. Enter the Polling interval.
This sets how often the job server polls the database to see if there are any new jobs. The default
is 15 seconds.
4. Enter the Maximum concurrent jobs. The default is -1. This is 1 concurrent job per processor.
Typing 0 stops job execution.
5. Click Add.
You should now add any applications, publish containers, and other objects to either a job
server cluster, or an individual job server. Jobs such as reconcile are not run until an application
is added to a job server or job server cluster.
Tip: to modify the properties of a job server, right-click the server name and click Properties.
Steps to Change the Content Store for the Job Server
1. On the job server computer, open IBM Cognos Configuration.
2. Under Data Access, Content Manager, Content Store, change the value for Database server
with port number or instance name.
Add Applications and Other Objects to a Job Server Cluster
Adding an object to a job server cluster means that when a job such as Publish is run, the job is run
by the job servers in the cluster.
You can monitor applications at cluster level and at job server level.
You must add the following objects to run jobs:
● a Contributor application
● an application folder
● View Publish Container
You need this if you are publishing using the view layout.
● Table-only Publish Container
You need this if you are publishing using the Table-only Layout.
Chapter 4: Configuring the Administration Console
Administration Guide 57

Chapter 4: Configuring the Administration Console
● a Planning Content Store
Step
● Click the job server cluster name, and click Add.
The window contains details about the objects monitored by the cluster. It lists only objects
that are directly assigned to the cluster, not those objects that are assigned to individual job
servers.
Add Objects to a Job Server
58 Contributor
Tip: Start or stop all job servers in the cluster by right-clicking the cluster name and selecting
Enable Job Processing or Disable Job Processing as required.
You can add objects to individual job servers.
Tip: You can see whether a cluster or individual job server is started from the icons in the adminis-
tration tree:
Icon
Steps
Description
Job server started.
Job server cluster started.
1. Click the name of the job server, and then click Monitored Applications.
2. Click Add.
Three panes of information appear.
Pane
Monitored objects held in
the Job Server Cluster
Monitored objects held in
this Job Server
Description
Shows the objects monitored by the cluster that the job server
is in.
Lists the objects monitored by the job server. It contains only
details of objects directly assigned to the server.
You can assign an application folder and its contents to a job
server or job server cluster as a monitored object. You can
also assign each application within an application folder to
a different job server. For more information on monitoring
application folders, see "Monitor Application Folders" (p. 59)

Pane
Job Tasks being processed
Description
Monitors the jobs that are being processed by the server:
by this Job Server ● data source: If you see N/A by an application folder, this
indicates that the folder may have more than one data
source (applications within an application folder can be
on more than one datastore).
● application name
● job type: the job being processed (p. 49)
● Process ID: identifies the process used to execute a job
task. Used for debugging.
● Thread ID: identifies the thread used to execute the job
task. A thread is created for each job task. Multiple
threads can be created per process. The number of threads
per process is set in the Maximum concurrent jobs option.
Used for debugging.
3. Right-click the job server name and select Enable Job Processing or Disable Job Processing as
required.
Remove Job Servers
You can automate this process, see "Job Servers (Macro Steps)" (p. 199), "Disable Job Pro-
cessing" (p. 199), or "Enable Job Processing" (p. 199).
A Job server can exist in only one Planning Content store at a time. You can either manually delete
the job server from the Planning content store and add it to the new one, or on the job server,
change the content store that it is associated with. For more information, see "Steps to Change the
Content Store for the Job Server" (p. 57).
Step
● In the Contributor Administration Console, right-click the job server name and click Delete
Job Server
Monitor Application Folders
An application folder can be assigned to a job server or job cluster as a monitored object. This adds
the applications held in the folder, which are not already being monitored, to the job server or
cluster, allowing a group of applications to be monitored in one single step. If applications are
subsequently added to that application folder, they are not automatically assigned to the job server
or cluster.
Chapter 4: Configuring the Administration Console
You can also remove an application folder from a job server or cluster in a single step. This removes
all the applications contained and monitored in that folder by that job server or cluster. You can
Administration Guide 59

Chapter 4: Configuring the Administration Console
still add individual applications within an application folder to be monitored by different servers
or clusters.
● To add the contents of an application folder to be monitored, select the application folder row
and click Add.
● To add individual applications from within an application folder, select the applications required
and click Add.
Creating, Adding and Upgrading Applications
You can create new applications, add existing applications to the server, or upgrade applications
by right-clicking Applications and selecting one of the following options:
● Create New Application (p. 65).
● Link to existing Applications (p. 60). This adds Contributor applications that exist on the
datastore server to the Administration Console.
● Upgrade Application (p. 329). You can import and upgrade Contributor applications created
in an earlier version of Contributor.
Remove Datastore Definitions and Contributor Applications
When you remove a Contributor application and datastore definition, only the entries from the
Planning content store are removed, the datastores still remain on the server. To delete an application
from the server, you must have Database Administrator (DBA) permissions. If you do not, contact
your database administrator.
Step
● In the Administration Console, right-click on the server name, or the application name in the
Administration tree and click Remove Application.
Tip: You can also assign applications to application folders. For more information, see
"Application Folders" (p. 68).
Adding an Existing Application to a Datastore Server
60 Contributor
There are several circumstances in which you might add an existing application to a datastore
server:
● During application creation, you selected the Generate datastore scripts and data files option.
In this case, before you can add the application, the script must be run by a database adminis-
trator, see "Running the Script.sql file (DBA Only)" (p. 69).
● You chose to create scripts during an application upgrade
● You want to link to an application that was created in another Planning content store.

Steps
To do this, you must first remove the application from the Planning content store table it cur-
rently resides in.
1. Right-click Applications in the Administration tree and click Link to existing Applications.
2. The Add existing applications window lists the applications that exist for the currently selected
datastore server. Click the application you require.
3. If the application was created in a different Planning content store, add an application ID. This
is used by the Web browser to identify the application. It must be a unique character string.
4. For applications created using the Script.sql file, select the XML package. The location of the
package.xml is the same as the location of the script.
5. Click Add.
Ensure that the application is added to a job server or job server cluster. For more information,
see "Add Objects to a Job Server" (p. 58).
The Monitoring Console
The Monitoring Console enables you to monitor the progress of the following processes running
in the Contributor Administration Console from one location:
● application (p. 52)
● job server clusters (p. 58)
● administration links (p. 52)
● macros (p. 194)
● deployment (p. 170)
Managing Sessions
Multiple administrators may administer an IBM Cognos 8 Planning - Contributor application at
any one time. However, to prevent data integrity issues, when a change is made to the development
model, it is locked. The lock is dropped when the administrator navigates to a different function
or closes the Administration Console. You can manually remove the lock by clicking the Remove
button on the Session Details area. Use this with caution because it could prevent other users from
saving changes.
You can automate the removal of an application lock. See "Remove Application Lock" (p. 223) for
more information.
The development model can be changed by the following:
● changing navigation
● changing orientation
Chapter 4: Configuring the Administration Console
Administration Guide 61

Chapter 4: Configuring the Administration Console
62 Contributor
● selecting grid options
● selecting application options
● selecting planner-only cubes
● creating Contributor help text
● selecting dimensions for publish
● modifying e.List, and rights
● selecting saved selections and access tables
● synchronizing with IBM Cognos 8 Planning - Analyst
● modifying datastore maintenance options
● resetting development to production.
The production model is updated during the Go to Production process. There are checks in place
to ensure that two jobs do not run concurrently. Additionally, when you create a job using the
Administration Console, you are prompted if a valid job of that type already exists and alerted that
this new job may overwrite the existing job.
Example 1
Administration Console 1: User A clicks Navigation in the Administration tree. At this stage, the
development model is not locked.
Administration Console 2: User B clicks e.List in the Administration tree, and makes a change. The
development model is then locked by User B. A further check is made to ensure that no changes
were made to the development application since it was last read by Administration Console 2. If
this is true, User B can continue to edit the e.List and save the changes.
Administration Console 1: User A edits Navigation. User A is informed that User B has the applic-
ation locked and is asked whether they want to take the lock. User A takes the lock from User B.
Because User B updated the development model since User A opened the Navigation page, the
development model is no longer up-to-date. The user is prompted and Navigation is re-loaded with
the updated development model and User A can continue to edit and save changes.
Example 2
Administration Console 1: User A opens Application Options and makes a change.
Administration Console 2: User B opens Orientation and makes a change. User B is prompted that
User A has the lock and User B takes the lock.
Administration Console 1: User A clicks Save. User A is prompted that User B now has the lock
and that changes made by User A will not be saved. The controls on Application Options are dis-
abled.
Example 3
Administration Console 1: User A opens Grid Options and makes a change.

Sending Email
Administration Console 2: User B opens the Publish Data and selects the detail for a publish. Because
this does not change the development model, there is no need for a lock to be taken. Both User A
and User B can work on the application concurrently.
You can send email to a user defined in an application using your default email program.
Steps
1. Click in the application containing the user you are sending an email to.
2. Click Send email in the toolbar .
The first time you do this, you may be asked to supply your mail provider connection details.
Refer to your mail provider documentation.
3. Choose to send an email to All Users or All Active Users, as defined in the application.
4. Click on the group of users you want to send email to, then click Mail. This opens up a new
email message in your standard email tool.
5. Create and send the email.
You then return to the Send email dialog box.
Chapter 4: Configuring the Administration Console
Administration Guide 63

Chapter 4: Configuring the Administration Console
64 Contributor

Chapter 5: Creating a Contributor Application
To create a Contributor application, you perform the following steps:
❑ If you have DBA rights to the datastore server, create a Contributor application using the
Application Wizard.
If you do not have DBA rights to the datastore server, create a script using the Application
Wizard, then send the script to the DBA who will run the script. After the script is run, add the
application to the Administration Console, "Adding an Existing Application to a Datastore
Server" (p. 60).
These processes create a development application. A development application is not seen by
the users, it is simply the application that you work on in the Administration Console.
This means you can make changes to the application without having to take it offline, reducing
the amount of time that users are offline to as little as a minute. This is the period of time taken
to integrate the new e.List items into the hierarchy and set the correct workflow states.
❑ Modify the application.
You can set the order in which the users are asked to go to each cube, click the dimensions that
make up the rows, columns and pages, add and modify the e.List, import users, define access
rights, and import data.
❑ Run the Go to Production process, see "The Go to Production Process" (p. 243).
This activates a wizard which creates a production application. This makes the application
available to end-users.
Creating a Contributor Application
Use the Application Wizard to create a Contributor Application.
Steps
1. In the Administration tree, under the name of the datastore server where the application is to
be created, right-click Applications.
A check is made to see if you are logged on with appropriate rights. If you are not, you are
prompted to log on. Click Next.
2. Select Create New Application from the menu.
A check is made to see if you are logged on with appropriate rights. If you are not, you are
prompted to log on. Click Next.
3. Select a library.
This is the Analyst library that your application will be based on. The D-Cube library list is for
information only and tells you which D-Cubes the selected library contains. Click Next.
Administration Guide 65

Chapter 5: Creating a Contributor Application
66 Contributor
4. Select the e.List.
The e.List is a dimension that is used to determine the hierarchical structure of an application.
For more information, see "The e.List" (p. 93).
When you select an e.List, the right-hand list tells you which D-Cubes in the application contain
this e.List.
5. Click Next.
The Administration Console checks the library to ensure that it can create the application. If
there are any errors or warnings, you can view these and save them to text file for more
investigation. If there are errors, the wizard will terminate. You can continue to create the
application if you only have warnings.
6. A window listing the statistics for the application will be displayed. This is for information
only. See "Model Details" (p. 68) for more information.
You can print the details on this window.
7. Enter application details as follows:
Detail
Application Display
Name
Datastore Name
Application ID
Location of datastore
files
Description
Defaults to the Analyst library name, but you can change this
during application creation. After an application is created, this
cannot be changed. There are no character restrictions. The
maximum length is 250 characters.
The name of the datastore application that contains the Contrib-
utor application database tables.
This defaults to the Analyst library name, stripping out special
characters. Only the following characters are allowed: lowercase
letters a to z and numeric characters. No punctuation is allowed
except for underscore. Maximum 30 characters (18 for DB2
OS390)
SQL Server only: Reserved keyword words are not allowed, see
your SQL Server documentation for more information.
This is used by the Web browser to identify the application. Only
the following characters are allowed: lowercase letters a to z and
numeric characters. No punctuation is allowed except for
underscore.
Enter the file path where the SQL Server datastore files will be
created on the administration server. You can browse the data
server file structure of file locations. Oracle and DB2 users do
not see this box, the location of datastore files is determined by
your datastore structure.

Detail
Location of datastore
backup files
Create and populate
datastore now
Generate datastore
scripts and data files
Save scripts in this
folder
Advanced
Description
Enter a location for the datastore backup files. The file location
must exist prior to creating an application and should be a dif-
ferent location than the datastore location.
This option creates the Contributor application and adds it to
the Administration Console tree. You only have this option if
you have appropriate DBA rights.
Select this option if you want to create a datastore script and
data files which can be used to create an application at a later
stage. This option is mandatory if you do not have DBA rights.To
create an application at a later date, the script must be run by a
DBA and the application added to the datastore. After the
application is added and you click on any of the branches, you
are prompted to select the package.xml file.
Enter or browse for a file location to save datastore scripts and
data files to.
Oracle applications
Specify the following options:
● Tablespace used for data (defaults to USERS)
● Tablespace used for indexes (defaults to INDX)
● Tablespace used for BLOBS (Binary Large Objects) (defaults
to USERS).
● Temporary tablespace
(Defaults to TEMP). This can be changed. This tablespace is
used for any automatically created publish datastores.
These tablespaces must exist.
DB2 UDB
Specify the tablespace name for data, indexes and BLOBS. It
defaults to USERSPACE1. Customized tablespace names can be
used. Tablespaces need to be at least 8000 pages.
8. Select the job cluster or job server to run the jobs for this application.
Chapter 5: Creating a Contributor Application
9. Click Next and then Finish. The application creation progress is displayed.
Administration Guide 67

Chapter 5: Creating a Contributor Application
Application Folders
If you generated datastore scripts and data files, send the script to the DBA. After your DBA
has run the script, you can add the application to the Administration Console "Creating, Adding
and Upgrading Applications" (p. 60).
You can use application folders to organize your applications into related groups. You can assign
job server clusters (p. 58) and access rights to groups of applications, making it easier to administer
multiple applications at the same time. For example, you can add or remove a group of applications
from a job server or job server cluster. An application folder can contain applications that exist on
more than one datastore.
When you assign an application to an application folder, it moves from under the Applications
branch of the tree to the relevant application folders.
Tips
Model Details
68 Contributor
● To remove an application from an application folder, right-click the application and select
Remove application from folder. The application is moved under Applications. If that was the
only application in the folder, the folder is removed from the Administration Console.
● To move an application between folders, you must first remove it from the original application
folder.
● Selecting Remove application removes the application from the Administration Console.
Steps
1. Before you create an application folder, at least one application must exist.
You must also have the right to assign applications to application folders.
2. Right-click the application name and click Assign Application to an Application Folder.
3. Click Create a new Application Folder and add the Application, or Assign the Application to
an existing Application Folder.
4. If creating an new folder, enter an appropriate folder name.
5. If you selected Assign application to an existing folder, select the folder name from the drop
down list.
6. Click Assign.
The model details window in the Application Wizard displays information about the application.
Exceeding these numbers may not be a problem for your application, but could slow down the end
user, and a redesign of the model in Analyst could help.

Warning
Number of Cubes
Number of D-Links
Total Number of Cells in
Application (per e.List slice)
Largest Cube
Total Number of D-List
Items in Application
Largest Dimension
Number
10
25
500,000
200,000
2,500
1,000
Running the Script.sql file (DBA Only)
Description
This is an optimum number of cubes that can be dis-
played in the Contributor Administration Console.
A large number of D-Links is not necessarily a problem.
However, greater than 25 D-Links could lead to some
specific performance issues that may be difficult to pre-
dict. This may slow both runtime performance and ini-
tialization times to an unacceptable level.
A large number of cells in the application will lead to
performance problems unless the model builder is able
to use no data settings in access tables to create e.List
specific models that are considerably smaller. Under
certain circumstances it is possible to distribute very
large models with Contributor, particularly if bandwidth
and server capacity is not an issue.
This restriction is similar to the Total Number of Cells
in Application. A large single cube can lead to perform-
ance problems at runtime, for example, breakback and
data entry can become slow, unless the cube is cut-down
using no data settings in access tables.
A very large number of dimension items can cause the
model definition to be very large. See also below.
The Contributor Web application is not designed to
carry a large number of dimension items across the rows
and/or columns. The application is optimized for views
that fit onto a single window. When lists are large, No
Data settings and cut-down models can be used to
reduce large lists down to a size that is more manageable
for each e.List item. There may also be usability issues
when manipulating large lists in the Administration
Console.
The DBA runs script.sql file using SQL, Oracle or DB2 as appropriate.
Database
SQL Server
To run the script, do the following:
Chapter 5: Creating a Contributor Application
open and run the file using SQL Server Query Analyzer.
Administration Guide 69

Chapter 5: Creating a Contributor Application
Database
Oracle
DB2
To run the script, do the following:
using SQL*Plus, at the prompt, enter @c:\script.sql.
run the script.sql using Command Center.
After you have run the script successfully, add the application to the Contributor Administration
Console. For more information, see "Adding an Existing Application to a Datastore Server" (p. 60).
Application Information
When you click the application name, the following application information is displayed:
Detail
Application Display Name
Datastore Name
Application ID
Library Name
Library Number
The e.List
Description
The name of the application as displayed in the Administration
Console.
The name of the application datastore.
A unique identifier used to identify the application in the Web
client.
The name of the library in Analyst that is used to create the
application.
The number of the library in Analyst.
The name of the dimension that is used as the e.List place-
holder.
Configuring the Contributor Application
70 Contributor
You can set options for the Contributor application:
● set global Web Client settings
● set the order in which the users are asked to go to each cube (p. 71)
● select the cube dimensions that make up the rows, columns, and pages of the cubes (p. 72)
● configure grid settings (p. 72)
● configure application settings (p. 74)
● designate which cubes can be viewed only by the planner (p. 78)
● create text for the users to see in the cube or Web client (p. 78)

Configure the Web Client
Configure Web client settings that apply to all Contributor applications. These settings can only
be applied by the Planning Rights Administrator.
Steps
1. In the Administration tree, click System Settings, and Web Client Settings.
2. To enable the Contributor applications to be deployed automatically over the Web, select Allow
automatic downloads and installations.
To enable automatic software updates, select Allow automatic client software updates.
3. To modify the separator that is used between names in emails sent from Contributor applications,
enter the separator in the Email character separator box.
4. To restrict the size of attached files:
● In the Attached Documents area, select Limit Document Size.
● Enter an amount (in megabytes) for the Maximum Document Size (MBs).
5. In the Allowable Attachment Types box, choose to either remove a selected file type by clicking
Remove or click Add to add a new allowable attachment type. At the end of the list of file type,
enter a label name and the file type extension in each box. Make sure you append the file type
extension with an asterisk (*).
Note: Changes made to the Attached Documents settings take effect without the need to perform
a Go To Production.
Set the Cube Order for an Application
Set the order in which the users are prompted to go to each cube. We recommend that you set the
order to be the same order in which the links run in the Analyst model. Users can switch between
cubes by clicking tabs.
You can provide instructions to be shown for each cube, see "Creating General Messages and Cube
Instructions" (p. 78).
Steps
1. In the appropriate application, click Development, Web-Client Configuration, and then Navig-
ation.
2. In the Set Cube Order box, click each cube name and move as required using the arrow keys.
3. Click Save.
Chapter 5: Creating a Contributor Application
The changes are visible to users after you run the Go to Production process.
Administration Guide 71

Chapter 5: Creating a Contributor Application
Set the Order of Axes
Select the cube dimensions that make up the rows, columns, and pages of the cubes. You can also
nest dimensions.
Steps
1. In the appropriate application, click Development, Web-Client Configuration, and then Orient-
ation.
2. Click the tab for the cube that you want to modify.
3. Click a dimension and move it using the arrows, to set it as a page, row, or column. Repeat
with the other dimensions if required.
4. If you want to create nested (merged) dimensions, place two dimensions under either Row or
Column.
Planners cannot change nested settings, even if they reslice.
5. Click Save.
The changes are visible to users after you run the Go to Production process.
If cubes that have dimensions defined as pages have dimension items with different access set-
tings, such as Read and Write, the cube opens with the first writable page selected by default.
If all items have the same access setting, the cube opens with the first selected page as created
in Analyst.
Change Grid Options
72 Contributor
If a user moves from one cube to another with the same dimension, the cube opens to the same
item selected in the previous cube.
Change grid options to affect the way the Web application appears and behaves.
Steps
1. In the appropriate application, click Development, Web-Client Configuration, and then Grid
Options.
2. Set the options you want.
3. Click Save.
Changes will be applied to the production application after running the Go to Production
process.

Option
Set Breakback
Option
Allow Multi
e.List Item
Views
Allow Slice and
Dice
Recalculate
After Every Cell
Change
Select Color for
Changed Values
Possible Unexpected Results Example
Description
When breakback is enabled and data is entered into a calculated cell,
data in other cells is automatically calculated from this data.
For example, you can distribute a total annual salary over twelve
months to calculate a monthly payment. For more information, see
the Analyst User Guide. All cubes have breakback selected by default.
If the Allow Multi e.List Item Views option is on, the user can select
a multi e.List item view, or a single e.List item view. This means they
can edit or view all contributions they are responsible for in one win-
dow. The default value is off because a large amount of memory may
be needed to open a multi-e.List item view.
If the Allow Slice and Dice option is on, users can swap a row or
column with a page or swap a page with a column or row heading.
The default value is on.
If the Recalculate After Every Cell Change option is on and a user
types data into the application, the data is recalculated as soon as the
focus moves from the cell. The default is Off, meaning that data is
calculated when pressing Enter.
You can specify the color of data in the grid for the following situ-
ations:
Saved data: the color of data with no change. The default is black.
Typed data not entered: the color of data that is typed but not entered.
The default is green.
Data entered but not saved: the color of data entered in the current
session but not saved. The default is blue.
The default colors are different in Analyst where the color of data that
is entered but not saved is red, not blue, and where detail/total is
blue/black, not normal/bold.
You may get unexpected results if you select this option with breakback On. For example, with
Breakback and Recalculate After Every Cell Change selected, in the example shown, type 240,000
in the total, and then type 40,000 in July, the total changes to 260,000 and the remaining months
have 20,000.
Chapter 5: Creating a Contributor Application
Administration Guide 73

Chapter 5: Creating a Contributor Application
With Breakback On and Recalculate After Every Cell Change Off, press Enter. The total holds as
240,000 and the remaining months have 18,182.
Change Application Options
74 Contributor
Change Application Options to affect the operation of the production application.
Steps
1. In the appropriate application, click Development, Web-Client Configuration, and then
Application Options.
2. Set the options you want.
3. Click Save.
Changes will be applied to the production application after running the Go to Production
process.
Option
History Tracking
Description
Use the History Tracking option to track actions per-
formed by users. When you select Action time stamps
and errors and Full debug information with data,
information is recorded in a datastore table named his-
tory.
Choose one of the following:
● No History
Does not track changes
● Action time stamps and errors
Tracks the times of users’ actions, including saves,
submissions, and rejections. This option is selected
by default.
● Full debug information with data
Tracks the times of users’ actions and records a
copy of the data at the point when each action takes
place. Because this option consumes a lot of
memory, use it only for debugging purposes.

Option
Cut-down Models
Allow Reviewer Edit
Allow Bouncing
Prompt to Send E-mail When
User Takes Ownership
Description
If cut-down models (p. 138) are used, a different model
definition is produced for each e.List item. This can
significantly speed up transmission to the client for
models with large e.Lists. However, if used inappropri-
ately, it could slow down performance.
Choose one of the following:
● No cut-down models
● For each aggregate e.List item (review level model
definition)
● For every e.List item
For more information about these options, see "Cut-
down Model Options" (p. 139).
If the Allow Reviewer Edit option is on, users with
review and submit rights to an e.List item can edit an
e.List item up to the review depth level, which is assigned
in the e.List window.
If the Allow Bouncing option is on, someone with
appropriate rights can take ownership of an e.List item
by clicking the Edit or Annotate button while the item
is being edited or reviewed by another owner.
If the Allow Bouncing option if off, ownership of an
e.List item can only be taken when it is not being edited
or reviewed by another user.
When a user has ownership taken away from them, they
are issued a warning and cannot save or submit their
data to the server. They can save to file by right-clicking
in the grid.
Chapter 5: Creating a Contributor Application
When this option is selected, user 1 is prompted to send
an email to user 2 when user 1 takes ownership of an
e.List item from user 2. The email is copied to other
people who have submit or save rights.
Administration Guide 75

Chapter 5: Creating a Contributor Application
76 Contributor
Option
Use Client-side Cache
Prevent Off-line Working
Prompt to Send Email on
Reject
Prompt to Send E-mail on Save
Prompt to Send E-mail on
Submit
Workflow page refresh rate
(minutes)
Web Client Status Refresh Rate
(minutes)
Description
If the Use client-side cache option is on, model defini-
tions and data blocks are cached on the client computer
so that they do not have to be downloaded repeatedly
from the server. This provides a huge reduction in the
network bandwidth required and is invisible to the user.
This is not possible on client computers where a security
policy prevents saves to the hard disk. When the user
requests the data by opening the grid, a mechanism
checks to see whether the data is cached on the client
machine and whether that data changed.
If the Prevent off-line working option is on, users cannot
work offline. Offline working is possible only when
cache on the client server may be used, but the client
side cache does not have to be enabled.
For more information, see "Working Offline" (p. 89).
Reviewers are prompted to send an email message to
current owners of contribution e.List items when they
reject an item. The email is sent to the person who sub-
mitted the e.List item, and copied to other people who
have submit or save rights and people who have assigned
rights for the review e.List item, that is the rights are
not inherited through the hierarchy.
The user is prompted to email all immediate reviewers
and copy (cc) all immediate owners when they save an
item.
The user is prompted to email all immediate reviewers
and copy (cc) all immediate owners when they submit
an item.
You can change the interval of time that the server is
polled to refresh the workflow page.
You can change the interval of time that the server is
polled to refresh the Web client status. Increasing the
refresh interval decreases the amount of Web traffic.
This may be desirable if there are a lot of clients, but it
also reduces the visibility of the data that the user gets
on the workflow state.

Option
Record Audit Annotations
Annotations Import Threshold
Annotations Paste Threshold
Display Audit Annotations in
Web Client
Allow Bouncing Example
Description
This records actions taken in the Web client, such as
typing, copying and pasting data, and importing files.
In addition, system link history is stored as an annota-
tion on the cube that was targeted by the link. When a
link is run, an annotation in the open e.List item. If the
link is rerun, the same annotation is updated. A history
dialog box shows all history related to the links that
apply to the open e.List items.
If enabled, users can view audit annotations for any cells
for which they have at least view access.
This option can greatly increase the size of the applica-
tion datastore, and should be used with care. It is Off
by default.
If a user imports a text file into the Web grid, this option
determines whether each row imported in a single
transaction is recorded separately, or all rows imported
are recorded in a single entry. If the threshold is set to
0, all rows imported in a single transaction are recorded
as a single entry.
If a user copies and pastes data into the Web grid, this
option determines whether each row pasted in a single
transaction is recorded separately, or all rows pasted
are recorded in a single entry. If the threshold is set to
0, all rows pasted in a single transaction are recorded
as a single entry.
Hides or shows audit annotations in the Web Client.
For example, if the Allow bouncing option is disabled, user 1 with edit rights to an e.List item
cannot edit while user 2 is editing. After user 2 stops editing, user 1 can edit after refreshing the
Web client status.
If the Web client status refresh rate is set to 0, user 1 can edit only if they close the grid and reopen
it. If the refresh rate is 0, the status is refreshed only when the user takes an action that connects
to the server. The default interval is five minutes, and the minimum interval is one minute. More
frequent polling has a negative effect on Web traffic over the network.
Chapter 5: Creating a Contributor Application
Automatic polling also refreshes the passport. If the Web client is inactive for half the passport
duration value, automatic polling ceases. For example, if default values are used, then after 1800
Administration Guide 77

Chapter 5: Creating a Contributor Application
seconds of inactivity the Web client polling will cease and after an additional 3600 seconds, the
passport expires. Any further Web client activity by the user requires re-authentication.
If you must, ensure that the passport duration value is respected exactly. For example, to comply
with financial regulations, the refresh rate must be set to 0 (zero). The passport then expires after
the configured duration of inactivity.
Create Planner-Only Cubes
Planner-only cubes are cubes that are seen only by the planner, or a reviewer with reviewer edit
rights to an e.List item. The data in a planner-only cube is fed into cubes that are seen by both
planners and reviewers.
You make a cube planner-only to reduce the amount of data a reviewer must view, and reduce the
amount of data that is aggregated, speeding up the aggregation process.
Steps
1. In the appropriate application, click Development, Web-Client Configuration, and then Planner
Only Cubes.
2. Select the cubes you want to make planner-only.
3. Click the Save button on the toolbar.
Creating General Messages and Cube Instructions
78 Contributor
You can create instructions that are shown to users in the Contributor application. An instruction
is text that appears when a user clicks Instructions on the Contributor application window.
Cube instructions can be different for every cube. You can create a brief one-line instruction that
appears below the cube tab name in the Web browser. You can also create a detailed HTML
formatted set of instructions, which the user views by clicking Help.
Use the full path to reference an image, so that it appears to all users.
Steps
1. In the appropriate application, click Development, Web-Client Configuration, and then Con-
tributor Help Text.
2. In the Enter Instructions text box, type instructions, using HTML tags if required.
You can create links to other Web pages, for more information, see "Creating Hypertext
Links" (p. 377) and "Customizing IBM Cognos 8 Planning - Contributor Help" (p. 375).
3. To enter help for each cube, click the cube name tab, and enter plain text help in the Simple
cube help or detailed plain text or HTML help in the Detailed cube help window.
Simple cube help must be text only, with no additional formatting. We suggest that you use
fewer than 100 characters to ensure that the text is visible.
Detailed cube help can be either HTML formatted text, or plain text, up to 3000 characters.
For more information, see "Customizing IBM Cognos 8 Planning - Contributor Help" (p. 375).

4. Click Save.
Changes are applied to the production application after running the Go to Production process.
Maintaining the Contributor Application
In the Application Maintenance window, you can configure application properties. In particular,
you can
● save application XML for diagnostic purposes (p. 79)
● show information about the application, such as the number of cubes, and the number of D-
Links (p. 79)
● set Admin Options (p. 79)
● select dimensions for publishing (p. 82)
● set Go to Production Options (p. 82)
Save Application XML for Support
Details about the Contributor application are held in XML format. If you have a problem with
your Contributor application, you can save the XML in the current state, and send the file to your
technical support.
You can automate uploading the Development application XML by using a macro, see "Upload a
Development Model" (p. 210) for more information.
Steps
1. In the appropriate application, click Development, Application Maintenance, and then
Application XML.
2. Click the Application Type: Development or Production.
3. Enter the XML file name.
4. Click Save XML to File.
5. If the file location changed, click Save.
View Application Details
Admin Options
The Application Details window provides information about the number of items in the application.
For more information on this window, see "Model Details" (p. 68).
You can configure import and publish options on the Development, Application Maintenance,
Admin Options window.
These options should only be configured by Database Administrators and are only available to
users with DBA rights. They can also be set directly in the datastore.
Chapter 5: Creating a Contributor Application
Administration Guide 79

Chapter 5: Creating a Contributor Application
80 Contributor
You do not need to run the Go to Production process for these options to apply, they are applied
as soon as you save.
Option
Datastore Version
Number
Import Block Size
Import Location
Import Options
Description
For information only.
The number of rows that are passed to the calculation engine at a time
during import. The default is -1, which means all rows are passed at once.
This is a temporary file location. Files are not deleted, but they may be
overwritten. When you import files, they are copied to this location on
the server.
You can specify parameters to BCP (bulk copy utility for SQL Server
applications) or SQL Loader command line parameters (import tool for
Oracle applications).
A BCP example is:
-B 10000
This parameter sets import text files to be uploaded in batch sizes of
10,000. Other possible parameters are [-h "load hints"] and [-a packet
size].
A SQL Loader example is:
DIRECT=TRUE
This parameter affects the number of lines that are uploaded and may
speed up the import process considerably, but it may require a lot of
memory.
When importing data, ensure that the database code page parameter
reflects the underlying data being imported. For example, when importing
Western European language data, use the Windows code page for Western
European, 1252. The parameter to use is -C=-C1252. For non-Western
European data, verify with your specific database documentation what
code page to use to ensure that it imports correctly.

Option
Publish Options
Optimize Publish Per-
formance
Generate Scripts
Table-only Publish
Post-GTP
Act as System Link
Source
Display Warning
Message on Zero
Data
Base Language
Description
If a foreign locale is used, the CODE PAGE parameter can be set here.
You can also set BCP options here.
You can change the default publish options by changing the resource file
located in \bin\. Each type of database has a different
resource file:
● DB2 - epEAdminDB2v7Resources.xml
● SQL Server - epEAdminSQL7Resources.xml
● Oracle - epEAdminORA8Reousrces.xml
These defaults are only applied if disable or manage indexing optimization
is selected.
You can increase publish performance by managing or dropping indexes
during the publish process. Manage indexing drops the index and then
recreates it when the publish is complete. Disable indexing drops the
index during the publish and enable indexing keeps the indexes intact.
If you select to disable or manage indexing, Publish Options are optimized
to improve publish performance.
Set this option to Yes to generates a script when any actions are performed
that require DDL commands to be run in the datastore, publishing data
and synchronize with Analyst.
Set this option to Yes if you want a full publish to occur after a model
change. The Reporting job detects if the model changes are incompatible
with the publish schema or link definition and performs a full publish to
correct the incompatibilities. If this option is set to No and errors are
detected, incremental publish is disabled.
Set this option to Yes if you want to allow the use of this application as
a source for a System Link.
Setting this option to Yes displays a warning message if you select the
Zero Data option when importing data "Steps to Prepare the Import
File" (p. 177).
This option determines language in which the Contributor application is
displayed if the user has not specified a preference in IBM Cognos Con-
nection. For information about translating applications see "Translating
Applications into Different Languages" (p. 185).
Chapter 5: Creating a Contributor Application
Administration Guide 81

Chapter 5: Creating a Contributor Application
Option
Scripts Creation Path
Select Dimensions for Publish
Description
This options sets the default location for script creation on the Contributor
Administration server.
You can select the dimension to use when linking to another resource, such as Analyst. Because
fewer records are published, the process is quicker.
Dimensions for Publish apply only for the View publish layout, and not the Table-only publish
layout. Dimensions for Publish in the Table-only layout are selected when you select cubes, or a
default dimension is used.
If a dimension is selected, that dimension is expanded while publishing to the datastore to incorporate
one column for each dimension item. For example, if a dimension named Months is selected, twelve
columns are published for each dimension item, rather than one generic Months column. This sig-
nificantly reduces the number of rows that are published and enabling differing data types per
column.
By default, None is selected. This means that none of the dimensions are expanded while publishing
and only one column exists for each dimension.
If you use data dimensions for publishing, select them before you run the Go to Production process.
You can then publish the production version of the application.
Steps
1. In the appropriate application, click Development, Application Maintenance, and then
Dimensions for Publish.
2. Click a tab to select a cube.
3. Click Select Dimension and click the dimension name to use as a data dimension.
4. Click Save.
Tip: Click Preview to view the data columns that will be published, either with a data dimension
selected or without.
Set Go to Production Options
82 Contributor
You can set production options prior to producing the application from the Go To Production
branch of the Administration Tree, under Development, Application Maintenance in the appropriate
application.

Option
Prevent Client-side
Reconciliation
Copy Develop-
ment e.List Item
Publish Setting to
Production
Application
Use the classic
Contributor client
Planning Package
Settings
Description
This option prevents client side reconciliation.
Typically, this option is used to prevent reconciliation on client machines
without much RAM. However, we do not recommend it.
When a production application is created, an online job runs that updates the
data blocks sequentially using the reconciliation process, see "Reconcili-
ation" (p. 54). Typically this happens on the job server. However, if an end
user requests an updated model before the reconciliation process takes place,
they are warned that the model is out of date and client side reconciliation
occurs. If the Prevent Client Side Reconciliation option is selected, a message
appears and users cannot access their e.List items until their e.List item is
reconciled.
If a user is editing either offline or online and this option is selected, when Go
to Production is run, they lose their changes. They can save the data by right-
clicking and saving to file.
This option enables you to specify whether the publish setting in the e.List
window should overwrite the settings in the Publish view layout e.List window.
If you import an e.List file with publish settings, or you edit the publish settings
in the e.List window, this option is automatically selected, and any publish
settings you made are carried over to the production application, overwriting
any settings made in the production application. Clear this option if you do
not want to overwrite the settings in the production application.
This option is only applied if changes were made to the Contributor application
since the last time Go to Production was run.
This option enables you to use the application with the classic Contributor
client.
If you switch an application from the web client to the classic client, any users
who are working offline will not be able to bring their data back online. The
application will not be available unless the classic client is installed.
When you set Go To Production Options, you must name the planning
package. Optionally, you can include a screen tip and a description for the
package.
Application access is restricted by the e.List. By default, when you create a
package, Overwrite the package access rights at the next Go To Production
is selected and the package access rights are based on the e.List. If, in IBM
Cognos Connection, you make changes manually to the package access rights
and want your modifications to remain after the next Go to Production, you
must clear this check box. For information about the Got to Production pro-
cess, see "The Go to Production Process" (p. 243).
Chapter 5: Creating a Contributor Application
Administration Guide 83

Chapter 5: Creating a Contributor Application
Datastore Options
84 Contributor
You set the datastore backup location and perform ad-hoc datastore backups in the Datastore
Maintenance branch of the Administration Tree, under Development, Datastore Options in the
appropriate application. You can also view information about datastore objects, such as datastore
tables that are associated with cubes in the application, and correct translation problems.
Option
Datastore Files
Location
Datastore
Names
Description
Location of datastore backup files:
Datastore backup backs up the entire application datastore, including the
production application immediately. This does not backup the publish datastore,
nor the CM datastore.
If you are using SQL Server, you can browse for a location. Oracle backups
can only be made to a location on the administration server, or machines with
access to the administration server. For DB2UDB applications, we recommend
that you backup manually. Refer to your provider documentation.
Restoring the application means that any contributions entered since the backup
was made will be lost. It is best practice to make backups when there is unlikely
to be much activity and you can stop the Web application from running while
the backup is being made.
Important: Depending on your organization's datastore policy you may not be
able to perform some datastore maintenance functions. If you do not have DBA
permissions, contact your DBA.
Location for publish container files:
Set the location for datastore container files created during publish.
This table displays Model Objects. In this instance, Model Objects are cubes
and their associated datastore tables.
Datastore Object Name lists the import datastore table names. If you click
Display row counts, the number of rows in each datastore table is displayed,
enabling you to see if, for example, there is any data in the export table without
having to look in the datastore manually. This may take a few minutes to
appear.
Import datastore tables are prefixed with im and import errors are prefixed
with ie.

Option
Translation
Maintenance
Tablespace
Description
When a translation is created, a row is created in the Language table in the
datastore, and some information is added to the model XML about the trans-
lation. If the information in the model XML and the information in the database
get out of step, you cannot run Go to Production. This may happen if you have
a problem in the Administration Console, or network problems.
The Datastore language tab box lists the rows that exist in the Language table
in the application datastore. The Model language table box lists the languages
that exist in the Model XML. If the languages listed in the two boxes are dif-
ferent, click Synchronize.
The Tablespace window displays the tablespace options that were chosen
during application creation.
Tablespace Options:
● Data
● Index
● Blobs
Chapter 5: Creating a Contributor Application
It also displays the temporary tablespace for the current Contributor application.
This window is only visible if the application runs on Oracle or DB2 UDB.
Administration Guide 85

Chapter 5: Creating a Contributor Application
86 Contributor

Chapter 6: The Contributor Web Client Application
There are two versions of the Contributor Web Client you can use, the Contributor Web Client
and the classic Contributor Web Client. Both clients allow users to contribute to plans and manage
submission and review workflow. However, the Contributor Web Client is easier to use while at
the same time it maintains all of the functionality of the classic client. By default all applications
use the Contributor Web Client, however, you can specify the classic Contributor Web Client for
an application by selecting Use the classic Contributor Client option in "Set Go to Production
Options" (p. 82).
For more information about the Contributor Web Client, see the IBM Cognos 8 Planning - Con-
tributor Web Client User Guide. For more information about the classic client, see the IBM Cognos
8 Planning - Contributor Browser User Guide and the IBM Cognos 8 Planning Contributor Work
Offline Guide.
To make a Contributor application available to users, you must set up a IBM Cognos 8 Web site,
see IBM Cognos 8 Planning Installation and Configuration Guide. To make changes to application
settings like cube order and grid options, see "Configuring the Contributor Application" (p. 70).
Users can access Contributor via the Web or using Contributor for Excel. See the Contributor for
Microsoft Excel ® Installation Guide for more information.
The Contributor Web Site
The Tree
The Table
When users log on to a Contributor application, they see a graphical overview of all the areas they
are responsible for, and the status of the data.
The Contributor interface has two panes. A banner across the top of the browser provides access
to User Instructions and Application Help.
The tree on the left side of the page shows the names of the areas that users are responsible for
contributing to (Contributions) and the areas that they are responsible for reviewing (Reviews).
Both appear in a hierarchical form. Depending on their rights, users may see either one of these
branches, or both. When the user clicks an item in the tree, a table with the details for the item
appears on the right side of the window.
Each item in the tree has an icon that indicates the current workflow state. For more information,
see "Workflow State Definition" (p. 295).
The table gives information such as the workflow state of the item, the current owner, the reviewer,
and when it last changed.
When users open a contribution, they can view or enter data depending on their rights and the state
of the data.
Administration Guide 87

Chapter 6: The Contributor Web Client Application
Data that users can edit has a white background. Read-only data has a pale gray background.
Data can be edited only if the icon indicates that it has a workflow state of Not started or Work
in progress.
Users can annotate data (p. 289).
Users can also reject contributions by clicking a reject button in the table.
If Contributor for Excel is installed, users can open their e.List items in Excel from the Contributor
Web application.
Set Web Site Language
You can set the language of the Contributor web site by assigning a translation to a user, group,
or role or in user defined properties in IBM Cognos Configuration. For more information on creating
and assigning a translation, see "Translating Applications into Different Languages" (p. 185). To
set IBM Cognos Connection language preference, see the IBM Cognos 8 Administration and
Security Guide.
If multiple languages have been assigned to a user, language precedence for the Contributor web
site are as follows:
● translation assigned to a user, group, or role
● translation assigned by user specified preference for Product Language defined in IBM Cognos
Configuration
● language selected in user preferences in IBM Cognos Connection
Access Contributor Applications
88 Contributor
You access Contributor applications from the IBM Cognos Connection portal.
Steps
1. Type the following URL in the address bar of the browser:
http://server_name/cognos8
2. In the upper-right corner, click Launch, Contributor. If you have access to more than one
package, click the package that you require.
If users have access to just one application, they are taken directly to that application. If they
have access to more than one, they are presented with a list to choose from.
3. To return to the IBM Cognos Connection portal, in the upper-right corner, click Launch, IBM
Cognos Connection.
Tip: You can copy the URL of a Contributor cell to the clipboard ready to be used by other
applications. This enables you to link directly to the cell from another application. In order for
the link to work, the Contributor application must be available on the computer and the user
must have appropriate rights.

Configure Classic Contributor Web Client Security Settings
The classic Contributor Web Client uses signed and scripted ActiveX controls. Ensure that each
user’s security settings for the Local Intranet zone are set to medium to accept these controls.
Steps to Allow ActiveX Controls
1. In Internet Explorer, select Tools, Internet Options, Security, Custom Level.
2. Under Reset custom settings, select Medium from the list, and then click Reset.
3. Click OK.
The Contributor Administration Console uses Microsoft Internet Explorer security settings to
communicate with the Web server. This may cause users to be prompted for multiple logons. To
prevent multiple logon prompts, ensure that each user’s browser security settings are set to one of
the automatic logon options.
Steps to Prevent Multiple Logon Prompts
1. In Internet Explorer, select Tools, Internet Options, Security, Local intranet, Custom Level.
2. Under User Authentication, select Automatic logon with current username and password, or
Automatic logon only in Intranet zone.
3. Click OK.
Linking to Earlier Versions of Contributor Applications
Working Offline
If you need to link to earlier versions of Contributor Applications, the Web sites for these applications
must be configured as described in the same version of the Contributor Administration Guide.
Working offline means that users can continue to work in situations when they are not connected
to the network.
Users can work offline only if the Prevent off-line working option is cleared (p. 74), and if they are
a user, or belong to the group or role associated with offline users. Offline working is possible only
when cache on the client computer can be used. When an e.List item is taken offline, the data is
stored in the offline store on the user's computer, see "The Offline Store" (p. 90). When the user
wants to do some work, they open up the offline application and work and save data as normal.
The application appears to work just like the grid in the Web Client, except there is no submit
button.
Chapter 6: The Contributor Web Client Application
Working offline should not be the standard working practice because reviewers cannot view the
current data and planners cannot receive updates when new data is imported. Ideally, users should
bring offline data online as soon as possible to keep the data changes visible.
A user can work offline, save their data, and end their session. If another user logs on to the same
computer as a different user, the new user cannot see the first user’s data.
Administration Guide 89

Chapter 6: The Contributor Web Client Application
Only a single e.List item or a standard multi-e.List item view can be worked with offline.
Working offline does not give access to everything in the cache and does not provide private e.List
item save.
The Offline Store
If there are multiple users with edit rights assigned to the e.List item, another user with appropriate
rights can edit the e.List item. The user who checked out the e.List item cannot check in the changes.
If the administrator makes more than one set of changes to the application before the user attempts
to check in the edited e.List item, the user cannot check in the changes. They can save the changes
to a .csv file when running the Go to Production process; the administrator is warned which users
will be terminated if they proceed. If the administrator made just one set of changes, the user can
check in the changes successfully.
When you bring offline data online, numbers that were changed and saved in the offline application
show as changed in the online grid.
Any annotations become read-only and data changes color to indicate that it was saved. Also,
attached documents are not available when working offline.
If you take an e.List item offline, you can continue working online on other e.List items.
When an e.List item is taken offline, the data is stored in the datastore in files called offlinestore.at
(allocation table) and offlinestore.store (object store) on the user's computer.
By default, the client computer cache is cleared after twelve days of inactivity. You can change this
using IBM Cognos Configuration.
Independent Web Applications
90 Contributor
You can create an independent Web application to customize an individual Web site for an
application. For example, you may want to use your own images.
Steps
1. Create a new directory and copy the webcontent files to a sub-directory of the new directory,
for example:
\\server\customweb\webcontent\
2. Set up the virtual directory alias to point to the new parent directory.
The virtual directories that you need to create are:
Alias
cognos8
cognos8/cgi-bin
Location
c8_location/webcontent
c8_location/cgi-bin
Permission
Read
Execute

For more information about configuring the Web Server, see the IBM Cognos 8 Planning
Installation and Configuration Guide.
Contributor for Microsoft Excel
Users can use Contributor for Excel to view and edit Contributor data using Excel, getting the
benefit of Excel formatting and Contributor linking functionality. Here are some examples of things
you can do:
● Create bar charts and other graphs from Contributor data.
● Create dynamic calculations from Contributor data.
● Create a calculation in Excel and link it to a Contributor cell.
As you update this calculation, you can choose whether to update the value in the Contributor
cell.
● Reuse custom calculations and formatting by saving the workbook as a template.
● Resize the worksheet so you can see more or less data on a page.
● Save data as an Excel workbook and work locally without a connection to the network.
To use Contributor for Excel, administrators must create a Contributor Web site, and client users
must install Contributor for Excel on their computers. For more information about design consid-
erations, see "Design Considerations When Using Contributor for Excel" (p. 311). For more
information about installation, see Contributor for Excel Installation Guide.
Note: You can only access Contributor for Excel from the Workflow page if you are using Microsoft
Internet Explorer. Regardless of Internet browser, you can access Contributor for Excel from within
Excel.
Chapter 6: The Contributor Web Client Application
Administration Guide 91

Chapter 6: The Contributor Web Client Application
92 Contributor

Chapter 7: Managing User Access to Applications
You manage access to Contributor applications through e.List and Rights in the Contributor
Administration Console.
The e.List defines the hierarchical structure of an application. It is used to determine who can enter
data, who can submit data, who can read data and so on.
Users are secured by IBM Cognos 8 security (p. 29).
Rights are defined by assigning users, roles, and groups to e.List items, and then by giving each
e.List item, and user, group, or role pairing an access level of Read, Write, Submit, or Review.
The e.List The e.List is used to determine who can enter data, who can only read data, who data is hidden
from, and so on.
An e.List is a dimension with a hierarchical structure that typically reflects the structure of the
organization. An e.List contains items such as departments in a company, for example, Sales,
Marketing, and Development. Each department may be divided into several teams, for example
Sales may be divided into an Internal Sales and an External Sales team.
Planners are assigned to items in the lowest level in the hierarchy. Reviewers are assigned to items
in the parent levels.
Customer
Service
All Departments
Operations Corporate
Production
& Distribution
Procurement
Sales Human
Resources
Finance Marketing IS&T
In the example shown, All Departments, Operations, and Corporate are reviewer e.List items. Any
users assigned to these e.List items with rights greater than view are reviewers. Customer Service,
Production & Distribution, Procurement, Sales, Human Resources, Finance, Marketing, and IS&T
are contribution e.List items, and any users assigned to these items with rights higher than view are
planners.
An e.List is created in two steps:
● The dimension that represents the e.List is created in Analyst.
Note: The e.List name cannot have a bracket ([ ]), brace ({ }), semicolon (;), or at sign (@).
● The file containing e.List data is imported into the Administration Console as a text file (p. 99).
The following example shows a simple e.List created in Analyst.
Administration Guide 93

Chapter 7: Managing User Access to Applications
94 Contributor
All Departments is the parent of Operations and Corporate. The Analyst calculation for All
Departments is
+Operations+Corporate
Operations is the parent of Customer Service and Production and Distribution. The Analyst calcu-
lation for Operations is
+{Customer Service}+{Production and Distribution}
The D-List used in Analyst to represent the e.List does not need to reflect the full hierarchy of the
e.List, but it must contain at least a parent and a child, and we recommend that it contains at least
one review item and two children so that weighted averages and priorities can be tested.
There are some circumstances when it helps to use the full e.List in the Analyst model, bearing in
mind that you still must import the e.List into the Administration Console as a text file or Excel
Worksheet.
For example:
● If you need to bring Contributor data back into Analyst for more analysis.
● When data already present in Analyst is needed in Contributor.
● If you are using Analyst simply as a tool for staging and tidying up external data.
If you export data from an Analyst D-Cube with the e.List into a Contributor cube, ensure that
the e.List item names in Analyst exactly match the Contributor e.List id.
The e.List should have a valid hierarchy. It is best practise not to have too many levels in the hier-
archy. Avoid having more than 20 child items assigned to a parent. This improves performance
and improves aggregation speed.

Multiple Owners of e.List Items
Ownership
You can assign more than one user, group, or role to an e.List item through the Rights pane in the
Administration Console. Do this when
● multiple e.List item owners share responsibility for a contribution, that is, they are job sharing
● an e.List item owner wants to delegate responsibility for completing a submission
● submission needs to be completed by a number of users sequentially
● the usual e.List item owner is absent, so a substitute user needs to make the submission
You may want to consider creating a group or role to contain multiple users, rather than assigning
multiple users, groups or roles to an e.List item. This allows users to be changed in the authentication
provider without you having to run the Go to Production process for these changes to be reflected
in the Contributor application. For more information about users, groups, and roles, see "Users,
Groups, and Roles" (p. 31).
There can be multiple owners of review e.List items as well as contribution e.List items.
Any users with edit rights to an e.List item may edit the contribution e.List item when
● The e.List item is in a Not started state, no changes have been made to it
● The e.List item is in a Work in progress state, changes have been made, but they either have
not been submitted to the reviewer, or have been submitted but have been rejected back to the
planner
● The e.List item has been taken offline for editing by another user, group, or role
Anyone with appropriate rights can take control of an e.List item from another user who may be
editing it. If they try to do this, they will receive a warning.
An owner of an e.List item is a user, group, or role that has rights greater than view. These rights
may be directly assigned, or may be inherited.
If more than one user, group, or role is assigned to an e.List item with rights greater than view, the
first one in the import file is the initial owner of the e.List item in the Contributor application. For
more information, see "Reordering Rights" (p. 112).
Unowned Items
If an e.List item has not been opened for edit, it is unowned. After it is opened for edit, the user,
group, or role that opened it is the owner.
Current Owner
The current owner is shown in the Contributor application and is the user, group, or role who is
editing or last opened an e.List item for edit. However, after they have opened the e.List item, they
can then choose to edit it, depending on the settings.
Chapter 7: Managing User Access to Applications
Someone can become the current owner by taking ownership of an e.List from another user.
Administration Guide 95

Chapter 7: Managing User Access to Applications
Note: After subsequent Go to Productions, the current owner is the last user, group, or role to have
edited the e.List item. The current owner is not reset.
Import e.List and Rights
96 Contributor
You can automate the import of the e.List and rights. For more information, see "Import e.List
and Rights" (p. 208).
Before importing, you must create import files in the correct formats. Note that the default files
supplied with the samples are examples only. For more information, see "e.List File Formats" (p. 99),
and "Rights File Formats" (p. 110).
If you have an e.List with more than 3000 items, they will not be displayed in a hierarchical format,
but in a flat format. Typically, you get the best results if you show fewer than 1000 e.List items in
a hierarchical format. You can set the Maximum e.List items to display as hierarchy under System
Settings.
Steps
1. Click Development, e.List and Rights and then click either e.List, or Rights.
2. Click the Import button.
If no users, groups, or roles have been imported, you cannot import rights.
3. In the appropriate tab, type the name of the source file, or browse for it.
4. Click Import.
5. if your file contains a header row, click the First row contains column headers box. If you
browse for files, the header row is automatically detected.
6. Click Delete undefined items, to delete existing e.List items, or rights that are not included in
the file that is to be imported. For more information, see "Delete Undefined Items
Option" (p. 98).
7. Click Trim leading and trailing whitespace to remove extra spaces at the beginning and end of
text strings on import.
8. Click Quoted strings to remove quotation marks on import.
9. Click Escape Character, and enter a character, if required.
10. Click the File Type.
If you are importing an Excel file, enter the name of the worksheet (within the Excel workbook)
in the box next to the Excel Worksheet option.
You can have e.Lists, and rights in one Excel file, but on separate worksheets. Ensure you name
each worksheet separately in Excel.
11. Click OK and then Save.

File Import Failure Message
If the import of your e.List and rights fails, for example, the structure of the e.List is incorrect, or
the import process itself fails, an error message appears. When errors are reported, some rows of
the file are not imported. You can view the rows that have errors. If the problem is caused by the
structure or contents of the file, correct the file and import again. If the failure was caused by an
application error, try to manually add an item. If this works, try re-importing the files again.
If the CamObjectName (name of user, group, or role) is not found during the import of the rights
file, a log file is created with the message: on the row of the
CamObjectName that is not found. Amend the import file to ensure that the correct CamObjectName
is referenced, or add the missing user to the namespace. This will also result if the user is not logged
into the namespace specified in the file. It is reported as an INVALID CAM OBJECT. To ensure
success, log into the namespace using File- Logon As.
If you still have a failure, contact Technical Support. You may be asked to supply a log file; this
can be opened through the Tools menu by selecting Show local log file. The file is named PlanningEr-
rorLog.csv.
The following table displays some of the error and warning messages that you may receive when
importing the e.List and rights.
Error or Warning
WARNING
WARNING
ERROR
WARNING
ERROR
ERROR
ERROR
Message
Circular reference at row x column
y EListItemName
Duplicate e-mail address at row x
column y emailaddress
Duplicate item at row x column y
Username
Duplicate item caption at row x
column y UserCaption
Duplicate user logon at row x column
y Userlogon
Empty item name at row x column y
Import table empty
Chapter 7: Managing User Access to Applications
Description
This occurs if e.List item a is the
parent of e.List item b and e.List item
b is the parent of e.List item a.
Duplicate e-mail addresses do not
cause technical problems.
Duplicate items are not allowed. This
row will not be imported.
Duplicate captions are not recommen-
ded.
This row is not imported.
e.List item names are mandatory in
the e.List import file and the rights
import file.
No rows are imported. Note that if
you import a file with just column
headings, it overwrites any existing
items and leaves them blank.
Administration Guide 97

Chapter 7: Managing User Access to Applications
Search for Items
Error or Warning
ERROR
ERROR
WARNING
ERROR
ERROR
WARNING
Message
Invalid cell at row x column y para-
meter
Invalid characters (ASCII control
characters not permitted) at row x
column y Illegal character z
Invalid parent name at row x column
y
Item name too long (maximum 100
characters) at row x column y
Mandatory columns missing colum-
nheadername
Review depth greater than view depth
at row x column y
Description
This occurs if an expected parameter
is incorrect, misspelled or missing.
See "Illegal Characters" (p. 387).
This message appears if an e.List item
does not have a valid parent. The
e.List item is still imported, but it
does not have a parent (and so is not
part of the hierarchy).
Item names and captions have a limit
of 100 characters.
A mandatory column is missing.
Review depth cannot be greater than
view depth. View depth is increased
to review depth.
You can search for items in the e.List and Rights panes in the Administration Console. You select
a column to search in, then type the first few characters that you want to find. You cannot do a
wild card search.
For example, if you want to find 001 New York, typing York will not find this string. Instead, type
001 New.
Steps
1. Select the column to search in, for example, Item Display Name.
2. Type the character string you want to search for.
3. Click Find.
Delete Undefined Items Option
98 Contributor
This option deletes any existing items that are not included in import files. Selecting Delete undefined
items when importing e.Lists and rights only has an effect when the e.List and Rights tables are
already populated.
If importing an updated e.List which has e.List items removed, any children of this item become
the top level (they are not removed).

e.List File Formats
If you delete e.List items from the e.List pane of the Administration Console, any children of these
items are also removed.
You can delete the entire e.List and rights tables by importing files containing only headings and
selecting the Delete undefined items check box. However, if you import a file that is completely
blank (no headings), you will receive warnings to say that compulsory columns are missing and the
e.List or rights remain unchanged.
The e.List can be in either Excel worksheet (xls) format, or in text file format, and you can specify
the delimiter.
The use of column headings is optional. If you use column headings, the columns can be in any
order. The column heading names must be the same as the column headings listed below. If no
column headings are used the column order shown below must be used.
Column heading in import file
EListItemName (p. 100)
EListItemParentName (p. 100)
EListItemCaption (p. 100)
EListItemOrder (p. 100)
EListItemViewDepth (p. 100)
EListItemReviewDepth (p. 101)
EListItemIsPublished (p. 101)
Example e.List File
Display Name
Item ID
Not applicable
Item Display Name
Not applicable
View Depth
Review Depth
Publish
The following table provides an example of an e.List file.
EListItem
Name
ALL
AMX
EAX
EUR
EListItem
ParentName
ALL
ALL
ALL
ALL
EListItem
Caption
All Sales
Regions
Americas
Asia
Pacific
Europe
EListItem
Order
1
2
3
4
Chapter 7: Managing User Access to Applications
EListItem
ViewDepth
-1
1
1
1
Status
Compulsory
Compulsory
Compulsory but may be left
blank.
Optional
Optional
Optional
Optional
EListItem
ReviewDepth
-1
1
1
1
EListItemIsPub-
lished
YES
YES
YES
YES
Administration Guide 99

Chapter 7: Managing User Access to Applications
100 Contributor
CEU
NEU
SEU
EUR
EUR
EUR
EListItemName
Central
Europe
Northern
Europe
Southern
Europe
5
6
7
0
0
0
0
0
0
YES
A unique identifier for each e.List item. This is an editable box and is case sensitive.
The following constraints apply:
● Must not be empty.
● Must contain no more than 100 characters.
● Must not contain control characters, that is, below ASCII code 32, see "Illegal Charac-
ters" (p. 387).
● Must be unique. Although it is case sensitive, differences in case do not count - the characters
must be unique.
This name is used when publishing data.
EListItemParentName
This column identifies which e.List item is the parent by referring to the e.List item name. The top
reviewer item refers to its own e.List item name as the parent name. This is case sensitive.
EListItemCaption
The name of the e.List item as it appears in the Contributor application.
The following constraints apply:
● May be empty (but will give a warning).
● Must not be more than 100 characters long (will be truncated, with a warning).
● Must not contain control characters (below ASCII code 32).
● May contain duplicates (will give a warning).
EListItemOrder
This is the order in which the e.List items appear in the application. This is optional, the default is
the order in the file.
EListItemViewDepth
The View depth column indicates how far down a hierarchy a user can view the submissions of
planners and reviewers.
The following values may be used:
YES
YES

● -1 indicates all descendant hierarchy levels.
● 0 indicates no hierarchy levels.
● 1...n where n is a whole number.
Defaults to 1.
EListItemReviewDepth
The Review depth column indicates how far down a hierarchy a reviewer can reject, annotate and
edit (if they have appropriate rights) contributions and reject and annotate submissions of reviewers.
The following values may be used:
● -1 indicates all descendant hierarchy levels.
● 0 indicates no hierarchy levels.
● 1...n where n is a whole number.
Defaults to 1.
EListItemIsPublished
This indicates whether an e.List Item will be published. Possible values are Yes, Y, No, N (not case
sensitive).
Defaults to No.
Export the e.List and Rights
You can export the e.List and rights as tab separated files, with or without column headings. This
enables you to update them in an external system such as Excel.
Steps
1. In the Administration Console, click the application name, Development, e.List and Rights and
then either e.List or Rights.
2. Click Export.
3. Enter or browse for the filename and location under e.List or Rights, for example: c:\temp\
export_rights.txt.
4. Select the Include column headings box if you want the column headings exported.
5. Select the Export box for each file you want to export.
6. Click OK.
Managing the e.List
The e.List table is populated with e.List data when you import an e.List.
Changes to the e.List are made to the production application following running the Go to Production
process (p. 243).
Chapter 7: Managing User Access to Applications
Administration Guide 101

Chapter 7: Managing User Access to Applications
Insert New e.List items
102 Contributor
To manage the e.List you can
● Insert new e.List items (p. 102).
● Manually reorder e.List items in the hierarchy (p. 103).
● Define whether data will be published to a datastore or not (p. 102).
● Delete an e.List item (p. 104).
● Preview an e.List item (p. 104).
● Find items in an e.List (p. 98).
We recommend that you modify the file used to import the e.List items and import the changed file
when you add new e.list items.
When this is not possible, you can manually insert new e.List items as described in the following
steps:
Steps
1. In the application tree, click Development, e.List and Rights and then click e.List.
2. Expand the parent e.List item and click in the e.List table where you want to insert the new
item. The new item appears above the item you clicked.
3. Click Insert and enter the information as follows:
Details
Item Display Name
Item ID
Publish
Description
The name of the e.List item (typically a business location) as it is
displayed to the user in the Web browser.
The name of the e.List item when imported from an external
resource such as a general ledger system or datastore. This may
be a code or a name independent of the e.List item name.
You can edit the item ID, but it must be unique within the
application.
This name is used when publishing data.
Indicates whether this e.List item is to be published to a datastore
or not. This only applies to the View Layout, not the Table Layout.
For more information, see "Selecting e.List Items to Be Pub-
lished" (p. 261).
Click either Yes or No.

Details
View Depth
Review Depth
4. To apply changes, click Save.
Description
Indicates how far down a hierarchy a user can view submissions
from planners and reviewers.
To assign view depth:
1. Click the View Depth cell of the appropriate e.List item.
2. Select or enter a number. To allow the reviewer to view all
levels below, click All. To disable the reviewer from viewing
the levels below, click None.
Note: When importing the e.List, All and None are represented
by -1 and 0 respectively.
For more information, see "View Depth Example" (p. 106).
Indicates how far down a hierarchy a reviewer can reject (or edit
if allowed), submissions from planners and reviewers.
Note that this setting is also influenced by the user's rights and
whether Reviewer Edit is allowed in Application Options (p. 74).
To assign review depth:
1. Click the Review Depth cell of the appropriate e.List item.
2. Select the required review depth. To allow the reviewer to
review all levels below, click All. To disable the reviewer from
reviewing the levels below, click None.
Note: When importing the e.List, All and None are represented
by -1 and 0 respectively.
Manually Reordering e.List Items in the Hierarchy
You can manually reorder e.List items.
For more information, see "Review Depth Example" (p. 105).
When you change the order of the e.List, making a planner a reviewer for example, a warning is
issued and any data that was entered with the user as a planner is lost when you run Go to Produc-
tion.
If a contribution e.List item becomes a review e.List item, the rights of a user assigned to that e.List
item are changed to the equivalent review rights as shown in the following table.
Contribution e.List item
View
Review e.List item
View
Chapter 7: Managing User Access to Applications
Administration Guide 103

Chapter 7: Managing User Access to Applications
Contribution e.List item
Edit
Submit
Steps
Deleting an e.List item
1. Click the e.List item.
Review e.List item
Review
Submit
2. Use arrows to move it to the required position.
The up and down arrows change the order of items, and the left and right arrows demote and
promote items in the e.List.
You can delete e.List items manually.
If you delete an e.List item, any data associated with this item is deleted when you run Go to Pro-
duction. When you save changes, a dialog box is displayed. This warns you of any data you could
lose, and you have the option to continue, and so lose the data, or cancel the deletion. If you delete
a review e.List item, all the items that make up the review e.List item are also deleted.
You cannot select and delete multiple e.List items at the same level, you can only delete one branch
of the e.List at a time.
Step
Previewing an e.List item
● In the e.List pane, click the e.List item and then click Delete and Save.
You can show individual e.List items in a pop-up box as they would be seen in the Web browser,
so you can see orientation, and the effects of selection.
Step
● In the e.List pane of the Administration Console, click an item and then click Preview.
The Effect of Changes to the e.List on Reconciliation
104 Contributor
If contribution or review e.List items have been added, deleted or moved, reconciliation takes place
after running the Go to Production process. Reconciliation is only required for the affected e.List
items. For more information, see "Reconciliation" (p. 54).
If e.List items have been added, new contribution or review e.List items and existing parents of new
e.List items are reconciled.

Rights by e.List Item
If e.List items have been deleted, parents of the deleted e.List items are reconciled. Note that the
actual e.List items are removed during the Go to Production process.
If e.List items have been moved, ancestor review e.List items of any moved e.List item are reconciled
(re-aggregated). This covers both review e.List items which were ancestors of the moved e.List item
in the old production application and review e.List items which are now ancestors of the moved
e.List item in the new production application. Note that if e.List items are simply reordered within
a hierarchy branch, no reconciliation is needed.
Moving an e.List item may also impact the pattern of No Data cells through saved selections and
access tables. Renaming an e.List item does not require reconciliation, but may impact the pattern
of No Data cells if saved selections based on names are used. If the pattern of No Data cells is
affected, reconciliation of all e.List items is required (data block transformation of contribution
e.List items and re-aggregation of review e.List items). Adding or deleting e.List items does not
affect the pattern of No Data cells.
Rights by e.List item displays the users, groups, and roles that are assigned to the selected e.List
item, and their rights. It can be displayed by selecting items in the e.List or Rights panes in the
Administration Console, and clicking Rights Summary.
A table with the following information is displayed:
Details
e.List Item Display Name
User, group, or role
Rights
Inherit from
Review Depth Example
Description
The e.List item display name.
The user, group, or role assigned to the e.List item.
The level of rights that the user, group, or role has to the
e.List item. See "Rights" (p. 107) for more information.
If the rights have been directly assigned to the user, group,
or role, this cell will be blank. If the rights have been inher-
ited, this indicates the name of the e.List item the rights have
been inherited from.
You can save the information on this screen to a text file by clicking Save to file and entering a file
name and location.
You can also print the screen by clicking Print.
The Review Depth column indicates how far down a hierarchy a reviewer can reject, edit or submit
submissions from planners and reviewers, depending on their rights (p. 107). The review depth must
be less than, or equal to the view depth.
Chapter 7: Managing User Access to Applications
Administration Guide 105

Chapter 7: Managing User Access to Applications
View Depth Example
106 Contributor
For example, you are the owner of the e.List item named Country A, which contains the regions
R1, R2, and R3, and each region has two cost centers: C1 and C2, and within each cost center are
three divisions: D1, D2, and D3 as shown below.
● If the review depth for Country A is 1, then the owner can only review the regions (the children
of your e.List item).
● If the review depth for Country A is 2, then the owner can only review the regions and the cost
centers.
● If the review depth for Country A is 3, then the owner can review the regions, cost centers, and
divisions.
● If the review depth for Country A is All (-1 in the import file), then the owner can review all
preceding e.List items. You can only set the review depth at All (-1) if the view depth is also
set at All (-1).
The View Depth column in the e.List section indicates how far down a hierarchy a user can view
planners' and reviewers' submissions.
For example, you are the owner of the e.List item named Country A, which contains the regions
R1, R2, and R3. In each region are two cost centers: C1 and C2, and within each cost center are
three divisions: D1, D2, and D3 as shown below.
● If the view depth for Country A is 1, then the owner can only view the regions (the children of
your e.List item).
● If the view depth for Country A is 2, then the owner can only view the regions and the cost
centers.
● If the view depth for Country A is 3, then the owner can view the regions, cost centers, and
divisions.
● If the view depth for Country A is All (-1 in the import file), then the owner can view all pre-
ceding e.List items.

Rights by User
Rights
Rights by User displays the level of rights for a user to an e.List item. It can be displayed by selecting
items from the Rights pane and clicking Rights Summary.
A table with the following information is displayed:
Details
User, group, or role
e.List item Display Name
Rights
Inherit from
Description
The name of the user, group, or role assigned to the e.List
item.
The e.List item display name.
The level of rights that a user has to the e.List item. For more
information, see "Rights" (p. 107).
If the rights have been directly assigned, this cell will be
blank. If the rights have been inherited, this indicates the
name of the e.List item the rights have been inherited from.
You can save the information to a text file by clicking Save to file and entering a file name and
location.
Rights for planners are determined by the settings in the Rights pane. By assigning rights, you can
configure user roles in the Administration Console, determining whether users can view, edit, review,
and submit.
Typically, you import a rights file. But you can also manually insert rights, and modify or delete
existing rights. If you want to make changes to the rights file, we recommend that you export the
file to ensure you have correct information, modify this file using an external tool such as Excel
and then import the file again.
You can assign more than one user, group, or role to an e.List item. For more information, see
"Multiple Owners of e.List Items" (p. 95).
Rights for reviewers are determined by the following settings:
● The rights setting.
● The view and review depth setting. Review depth gives the right to reject (or edit if reviewer
edit is on) to a specified depth. This is set in the e.List pane in the Administration Console.
● The Allow Reviewer Edit option in the Application Options pane in the Administration Console
(p. 74).
Chapter 7: Managing User Access to Applications
● If a reviewer has two different levels of rights for the same e.List item the higher rights applies.
Rights may be assigned directly or inherited. See the following example:
Administration Guide 107

Chapter 7: Managing User Access to Applications
If the reviewer is assigned with submit rights to a parent e.List item which has a review edit depth
of 1, and reviewer edit is allowed, the reviewer has the right to view, edit, reject and submit the
child e.List item. These are inherited rights.
The reviewer is also directly assigned to the child item with view rights. These are declared, or directly
assigned rights.
You can only directly assign one set of rights to a user for a specific e.List item. If you insert a
duplicate record you receive a warning, and the rights that appear lower down in the rights table
are deleted.
Tip: If you specify more than one reviewer for an e.List item, in the workflow page for the Contrib-
utor application, an email link named email all is displayed. If you specify one reviewer, the name
chosen in the User, Group, or Role column is displayed, and you should ensure that a descriptive
name for the user, group or role is chosen.
Submit Rights
An e.List item can have no user with submit rights (that is, no user is assigned or has resolved rights
through Reviewer depth to the e.List item). If this is the case, contributions are not submitted and
the item and its parents in the hierarchy cannot be locked.
We recommend that the administrator reviews the Rights pane to ensure every e.List item has at
least one user with submit rights (who may be a reviewer with appropriate rights).
Inherited Rights
If the reviewer is assigned with submit rights to a parent e.List item which has a review depth of 1,
reviewer edit is allowed, the reviewer will have the right to view, edit (contribution e.List item only)
reject and submit the child e.List item. These are inherited rights.
The following tables explains what rights mean when they are assigned to planners and to reviewers.
It also explains how the rights can be affected by different settings.
Actions Allowed for Review e.List Items
108 Contributor
The following actions are allowed for Review e.List items.

Rights
Submit
Review
View
Reviewers
With reviewer edit on (p. 74), reviewers can
● edit, submit, and reject contribution e.List items if the e.List item they are
assigned to has sufficient review depth
● submit or reject child review e.List items if the e.List item they are assigned to
has sufficient review depth
● submit their own review e.List item
● annotate their own review e.List item and children to review depth
With reviewer edit off, reviewers can
● submit their own review e.List item
● reject children to review depth
● annotate their own review e.List item and children to review depth
Note: when Reviewer edit is off, reviewers cannot edit contribution items
With reviewer edit on, reviewers can
● edit contribution items if the e.List item has sufficient review depth
● submit and reject child e.List items if the e.List item they are assigned to has
sufficient review depth
● annotate their own review e.List item and children to review depth
With reviewer edit off, the reviewer cannot edit or submit any e.List items, but can
● reject child e.List items if the e.List item they are assigned to has sufficient
review depth
● annotate their own review e.List item and children to review depth
View assigned e.List items and children to view depth. Cannot annotate, reject, edit,
or submit.
Actions Allowed for Contribution e.List items
The following actions are allowed for Contribution e.List items.
Rights
Submit
Edit
Planner
Chapter 7: Managing User Access to Applications
View, edit and save, submit and annotate assigned e.List items.
View, and edit assigned contribution e.List items. Can annotate. Cannot submit.
Administration Guide 109

Chapter 7: Managing User Access to Applications
Rights
View
Rights File Formats
110 Contributor
Planner
View assigned e.List items. Cannot annotate.
Rights can be in Excel Worksheet (xls) and text file format.
The use of column headings is optional. If you use column headings, the columns can be in any
order. The column heading names must be the same as the column headings listed below and are
case sensitive. If no column headings are used, the order shown below must be used.
Column heading in
import file
EListItemName
CamObjectName
EListItemUserRights
CamNamespaceName
CamObjectType
EListItemUserRights
Display heading
Item ID
User, Group, Role
Rights
Namespace
CAM Object Type
Description
Identifies the e.List item that you are setting rights
for. This must match an e.List item id in the e.List
import file and is case sensitive.
The display name of the user, group, or role as it
appears in IBM Cognos 8.
See "EListItemUserRights" (p. 110).
The display name of the security namespace as it
appears in IBM Cognos 8.
Either User, Group, or Role.
The following rights can be used. These are not case sensitive.
Rights
View
Edit
Review
Submit
Description
View rights only.
View and edit, but cannot submit.
View, submit contribution e.List items
(not review e.List items) if they have
sufficient reviewer depth rights, reject
and save to edit depth.
View, save changes, submit.
Applies to
Contribution and review e.List items.
Contribution e.List items.
Reviewer e.List items.
Contribution and review e.List items.

EListItemName
Finance
Production
Marketing
If the import file specifies Review for a contribution e.List item, or Edit for a review e.List item, on
import, the Administration Console changes the settings so that Review becomes edit for a planner
and Edit becomes Review for a reviewer.
For more detail, see "Rights by User" (p. 107).
You can assign more than one user to an e.List item. If more than one user is assigned to an e.List
item with rights higher than View, the user that is first in the import file is the initial owner of the
e.List item in the Contributor Web application. When you insert rights manually, they are appended
to the bottom of the rights table and it is not possible to reorder the rights at e.List level. The only
way to reorder the rights at e.List level is to export the file, delete the existing rights, modify the
import file and import the new file.
Note: If you have imported a rights file containing three columns, and you import a new rights file
containing only the first two columns, any new rights added will take the default value of submit,
and any rights that existed in both the old and the new files will remain unchanged. If the new
rights file contains three columns, any rights existing in both the old and the new files are overwritten
with the new rights.
For more information, see "Multiple Owners of e.List Items" (p. 95) and "Rights by e.List
Item" (p. 105).
Example Rights File
CamObjectName
Mary
Planning Contributor
Users
Administrator
Modify Rights Manually
EListItemUserRights
SUBMIT
EDIT
VIEW
CamNamespaceName
ntlm
Cognos
ntlm
CamObjectType
User
Role
User
In the Rights pane in the Administration Console, you can specify whether users can view, save,
submit and so on.
Typically, you assign rights to users by importing a rights file, (p. 96). But it is also possible to
manually insert rights, and modify or delete existing rights. You can also export a rights file that
can be modified and imported again if necessary. For a detailed description of each level of rights,
see "Rights" (p. 107).
The rights that a user may have are also affected by the view and review depth settings, set in the
e.List pane in the Administration Console, and the Reviewer edit setting, set in the Application
Options pane, (p. 74). A user may have directly assigned rights, or inherited rights. You can see a
summary of the rights per user and per e.List item by selecting a line and then clicking the Rights
Summary (p. 107).
Chapter 7: Managing User Access to Applications
Administration Guide 111

Chapter 7: Managing User Access to Applications
You can assign more than one user to an e.List item, see "Multiple Owners of e.List Items" (p. 95)
for more information.
Steps
Reordering Rights
112 Contributor
1. In the appropriate application tree, click Development, e.List and Rights, and then Rights.
2. Click Insert.
A blank line is inserted into the rights table.
3. Select the e.List item by clicking in the Item Display Name cell.
4. Select the User, Group, or Role.
● Click the name you want to add.
If the name is not displayed, you can add a role or group to the filter.
Tip: You can choose to display the complete list of users, groups, or roles by selecting Show
all descendants. Depending on the number of items in the list, this may take a while to
display. If this box is not selected, only the direct members of the group or role are shown.
● Click the browse button (...).
● Click the appropriate namespace.
● Select the group, or role. Any users who are members of the group or role that you select
will be added to the list.
● Click the green arrow button and click OK.
You can now select the user, group, or role that has rights to the e.List item.
5. Select the rights by clicking the rights cell. If the e.List item is a Review item, you can choose
View, Review, or Submit. If the e.List item is a contribution item, the rights you can select are
View, Edit, or Submit. For more information, see "Actions Allowed for Contribution e.List
items" (p. 109).
The Item ID is the external identifier for the e.List item and is the key for importing.
6. To order the rights by hierarchy, click Order by hierarchy.
If you assign multiple users to an e.List item, the user that is highest in the rights table is the
current owner (p. 95) when the Go to Production process is run.
You can search for rights in this window. For more information, see "Search for Items" (p. 98).
If more than one user, group, or role is assigned to an e.List item with rights higher than View, the
user, group, or role that is first in the import file is the initial owner of the e.List item in the Con-
tributor application. When you insert rights manually, they are appended to the bottom of the rights
table and it is not possible to reorder the rights at e.List level. The only way to reorder the rights
at e.List level is to export the file, modify the import file and import the new file.

Viewing Rights
You can view rights listed by e.List item and rights listed by user by selecting one or more lines in
the rights table and clicking Rights Summary.
You can print and save to file the rights by e.List (p. 105) and rights by user (p. 107).
Validating Users, Groups and Roles in the Application Model and Database
You can validate users, groups, and roles that are used by the application model and database
against the Cognos 8 namespace.
The validate function checks name information used by the Contributor Administration Console
against the Cognos 8 namespace. If any names have been changed or removed, you can update the
information used by the Contributor Administration Console to match the namespace.
If there are no invalid items and only changed items, the database table only is updated. Therefore,
there will be no cut-down models job run during Go to Production.
If there are invalid items and changes then the model is also updated and a cut-down model job
will run during next Go to Production.
Steps
1. In the tree for the application, click Development, e.List and Rights and then Rights.
2. Click Validate.
3. If there are invalid or out-of-date users, groups, or roles, and you want to update them, click
Update or click Cancel.
Chapter 7: Managing User Access to Applications
Administration Guide 113

Chapter 7: Managing User Access to Applications
114 Contributor

Chapter 8: Managing User Access to Data
You control access to cells in cubes, whole cubes, and assumption cubes using access tables. Saved
selections are groups of dimension items that support and simplify access tables.
For example, in an Overheads dimension, you might want to show only those items relating to
travel expenses. This allows you to show users only those items that are relevant to them.
You define access for contribution e.List items, but access is automatically derived for review e.List
items.
The key difference between using saved selections and defining access directly in access tables is
that saved selections created on dimensions within an application are dynamic. That is, they change
when definitions in the dimension upon which they are made are changed (when an application is
synchronized following changes to the IBM Cognos 8 Planning - Analyst model).
Imagine the following scenario:
You have a dimension that contains:
● Product 1
● Product 2
● Total Products (sum of all)
● A saved selection is made which is the enlargement of the "Total Products" subtotal.
If a change is made to the Analyst model which modifies the dimension to now contain:
● Product 1
● Product 2
● Product 3
Saved Selections
● Total Products (sum of all)
The saved selection, which is the enlargement of the "Total Products" subtotal, now includes all
three products without any change being made to it. In other words, it is dynamic and changes as
the definitions in the application change following synchronization.
When you create saved selections, you name and save selections of items from a dimension. A
selection is a collection of dimension items, and could be lists of:
● Products sold by a particular outlet
● Product/Customer combinations
● Channel/Market combinations
Administration Guide 115

Chapter 8: Managing User Access to Data
● Employee lists
● Range of months for a forecast
Once you have created a saved selection, you can set levels of access to this item. For more
information, see "Creating Access Tables" (p. 123).
You cannot explicitly define an access table on a review e.List item. If you create a saved selection
on the dimension selected as the e.List, you cannot select any review e.List items.
Steps
1. In the application tree, click Development, Access Tables and Selections, and Saved Selections.
2. Click New in the Saved Selections form, and enter details as shown below:
Detail
Selection name
Dimension
3. Click OK
Description
Enter a name for the selection
Click this box to show a list of dimensions, then click one.
4. To edit the selection rules, click in the Selection Name or Dimension column of the saved
Editing Saved Selections
116 Contributor
selection, then click Edit. This opens the Dimension Selection Editor, see "Editing Saved
Selections" (p. 116) for more information.
In the Dimension Selection Editor, you edit and refine saved selections.
The steps to edit a saved selection are:
● Open the Edit window for the selection you will be editing.
● Choose the items you want to show from the Show list box.
● Make your first selection.
● Refine your selection by making a second selection if required.
Steps
1. Open the Edit window.
In Saved Selections, click on the selection you are going to edit, then click Edit.
2. Choose the items you want to show.
The default settings show all the items in the dimension, or e.List. In the case of long and
complex lists, narrow down the dimension items you want to display by selecting an item under
Show. A check mark indicates either a first or second selection, or a result (=).

Item
All
Detail
Calculated
Filter
First Selection
Second Selection
Results Selection
Description
Displays the full list of items in the dimension.
Only Detail items are displayed, that is, all dimension items except
for calculations.
Only those items that are calculated are displayed.
Shows a selection of items based on a filter that you define.
When you select a filter, the filter works on the dimension item
name only, not the values contained in the cells.
Select: = to select items that equal the criteria. to select items
that do not equal the criteria.
Use: ? to represent any single character. * to represent any series
of characters. This must not be used as the first character in a string.
Enter the filter, for example selection = O* (with Case Sensitive
selected shows all items beginning with a capital O). You can make
the filter case sensitive by selecting the Case Sensitive box.
Example: Type 015* to filter on all dimension item names beginning
with 015.
Displays the results of the first selection.
Displays the results of the second selection.
Displays the results of the first and second selections.
3. To make a selection, click one of the following options from the First Selection list box:
Option
All
Description
Selects all items in the dimension. This is useful when used in
combination with Second Selections, for example:
● First Selection: All
● Except check box: selected
● Second Selection: Filter =9*
Chapter 8: Managing User Access to Data
This selects all items except those beginning with 9.
Administration Guide 117

Chapter 8: Managing User Access to Data
118 Contributor
Option
Detail
Calculate
List of items
Enlarge
Filter
Description
Selects all detail items (all dimension items that are not calculations).
The benefit of using this item is that if the list of detail items change,
the saved selection is updated automatically.
Selects all calculated items. If the list of the calculated items change,
the saved selection is updated automatically.
Click the items to be selected then move them to the First Selection
list box by clicking the right arrow.
If the list changes, the saved selection must be updated.
Includes all items that make up a calculated item, either directly or
indirectly.
Click one or more calculated items and then move them to the First
Selection list box by clicking the right arrow.
Shows a selection based on a text search criterion. For more
information, see "Editing Saved Selections" (p. 116).
If this is a simple saved selection, click OK to close the Edit window and then click Save to save
the selection.
4. Create a selection rule:
● Select one of the options:
Option
Except
Union
Intersect
Description
All items selected in the first selection, except those selected in the
second selection.
The union of all items included in both selections.
Items that are the same in both the first selection and second
selections.
● Make a selection from the Second Selections list box.
The results are displayed under Show. Click OK.
● Click Save.

Deleting Saved Selections
You cannot delete a saved selection that is used in an access table. It must be removed from the
access table first.
Step
Access Tables
● In the Saved Selections pane, click the selection and then click Delete.
Create access tables to determine the level of access users have to cubes, saved selections, and
dimension items. access tables can reduce the volume of data a user has to download, especially
when used in conjunction with cut-down models and the No Data setting. For more information,
see "Cut-down Models" (p. 138).
You can set access levels for an entire cube (contribution or assumption cubes) or for specific
selections of cells in a cube (contribution cubes only).
For entire cubes, you can choose Write, Hidden, or Read for contribution cubes and Hidden or
Read for assumption cubes (p. 120). Access set at cube level applies to all planners.
Access to specific selections of cells is controlled using access tables. Do this by choosing one or
more dimensions, and defining access to sets of items in these dimensions.
If you need cube-level access to vary by planner, select the Include e.List option. You must also
include one of the other dimensions of the cube (preferably the smallest), and select All items for
this dimension when creating the access table.
Access tables using more than two dimensions (this includes the e.List) should be avoided where
possible. This is because when you perform an action in the Administration Console that makes
use of the access tables, the system needs to resolve the access tables in order to determine what
access level applies to each cell, and which cells have data. If an access table is very large, this can
slow down the system considerably. For more information, see "Large Access Tables" (p. 129).
It is not possible to create planner-specific views of assumption cubes. If this is required, you should
convert the assumption cube to a contribution cube in Analyst by adding the placeholder e.List.
Then you should move any assumption data present in the Analyst D-Cube into Contributor using
AnalystContributor links (p. 347).
You cannot explicitly define an access table on a review e.List item. If you create a saved selection
on the dimension selected as the e.List, you cannot select any review e.List items.
Access Tables and Cubes
There are two types of cubes in Contributor: assumption cubes and all other cubes. The access level
you can set depends on the type of cube.
Assumption Cubes
An assumption cube contains data that is moved into the Contributor application on application
creation and on synchronization.
● They do not contain the e.List, therefore data applies to all e.List items.
Chapter 8: Managing User Access to Data
Administration Guide 119

Chapter 8: Managing User Access to Data
● They are not writeable. The default level is read-only.
● You can only set access levels to a whole assumption cube.
Other Cubes
All of the other types of cubes used in Contributor:
● Must contain the e.List.
● Are writeable by default, but can also be set to be read-only, contain no data, or be hidden.
● May contain imported data.
● Are usually used for data entry.
● You can set access to selections of cubes, whole cubes, and to dimension items.
● Can be set to planner-only cubes (p. 78) which hides the cube from the reviewer.
When you create an access table, you select one or more dimensions, and define access to sets of
items in these dimensions. By default, access tables include the e.List, so you can vary access setting
by planner. You can opt not to include an e.List in an access table, in which case the setting applies
to all planners, for example, you might want to make a budget version read-only for everyone. You
cannot have planner specific access settings for assumption cubes. This is because they do not contain
the e.List.
Rules for Access Tables
120 Contributor
You can apply rules when setting access levels for cubes, saved selections, and dimension items.
You can set the following levels of access for cubes, saved selections, and dimension items.
● Write
● Read
● Hidden
● No Data
Access rules are resolved in the order in which they appear in the table. If more than one rule is
applied to an item, the last access rule assigned is given priority. For example, you might want to
set all items to No Data, and then subsequently set individual items to Read, Write, or Hidden.
If you have defined more than one access table for a cube, the access setting that will apply is the
lowest level of access amongst all the access tables, for example, a hidden access setting has priority
over write.
No two access tables that control the same dimension can be applied to the same cube.
You receive a warning if you create an access table that contains more than two dimensions as this
can slow down the Administration machine if you import large amounts of data.
If no access levels are set, the following defaults apply:
● All cubes apart from assumptions cubes have a global access level of Write.

● Assumption cubes (cubes used to bring data into an application) have a global access level of
Read.
Access Level Definitions
Selecting access levels of Read, Write, and Hidden have no affect on the way links or importing
data work. The access level No Data does affect links and importing data.
You can set the access level to write, read, hidden, or no data.
Write
This is the default for all cells in a planner’s model. Write access means that users with appropriate
rights can write to this item, provided the e.List item is not locked (the locked state occurs when
data is submitted to a reviewer).
This option cannot be set on assumption cubes.
You can breakback from a writeable calculation, unless all detail items used by the calculation are
set to read or hidden.
If a calculation uses other calculated items, and these calculated items are set to read or hidden,
breakback is possible. If all of the items used by the calculation, either detail or calculated, are set
to read, breakback is not possible.
Read
Cells marked as read are visible but cannot be changed by the planner. For example, a planner
cannot type into any read-only cells, paste will skip read-only cells, and breakback will treat read-
only detail cells as held. However, planners can change values in read-only calculated cells; read-
only calculated items will still be recalculated (they are not treated as held). This extends to break-
back: if a writeable calculation, for example, Grand Total, uses some read-only calculated items
such as Total Group A, a planner can breakback from the writeable calculation (Grand Total)
through the read-only calculations (Total Group A). This is only possible when at least some of the
items feeding a calculation are writeable. It is never possible to change a cell that is a D-Link target.
Detail cells targeted by D-Links are read-only as normal and will treated as held by breakback.
Calculated cells targeted by D-Links are also read-only, but these cells cannot be changed by forward
calculation or breakback due to planner entry.
Read is the default value for the following:
● All cells in assumption cubes.
● All cells targeted by D-Links. These can never be changed directly by the planner.
● Calculated cells in cubes for which breakback is disabled.
● Calculated items are read-only when none of their precedent items are writeable. For example,
a subtotal will automatically be read-only if all items summed by the subtotal are read-only
(whether they are read-only due to access tables or D-Link targets, or due to submission of
contribution e.List items).
Chapter 8: Managing User Access to Data
Administration Guide 121

Chapter 8: Managing User Access to Data
● Calculated items are set to read-only when breakback is not possible because of the type of
calculation; in particular, the result and outputs of BiFs, and constant calculations are always
read-only.
● A planner can never change read-only detail cells, but read-only totals are not held.
Hidden
Hidden cells are not visible to a planner, but otherwise they are treated in the same way as read-
only cells. For example, breakback does not target hidden detail cells, but goes through hidden
calculated cells if at least some of the detail cells the calculation uses are writeable. Hidden calculated
cells are recalculated, and so on. This means that intermediate calculations, for example, in a cube,
or even entire intermediate calculation cubes, can be hidden without affecting model calculation
integrity.
If all cells in a cube are hidden for a particular planner, the cube is removed entirely in the Web
browser view, but the data is still downloaded to planners.
Note: You cannot breakback over hidden detail cells.
No Data
No Data cells do not contain any data. When used by calculations they are assumed to contain
zero.
No Data access settings, regardless of whether cut-down models are used, can affect:
● Volume of data processed in memory, which in turn affects calculation speed. This is because
the calculation and link engines do not process No Data cells where possible, so No Data areas
in general reduces memory requirements and speeds up recalculation.
● Data block size, which in turn affects download and upload speed (when opening the grid and
when saving or submitting) can reduce network traffic. This also affects the speed of aggregation
when data is saved, and hence reduces the load on the run time server components.
No Data access settings, used in conjunction with cut-down models, can affect the model definition
size. It can improve download speed on opening and reduce network traffic, but also increases the
time it takes to run the Go to Production process.
Updating No Data Access Settings
122 Contributor
When you run Go to Production and changes have been made to access tables that result in a dif-
ferent pattern of No Data cells, a reconcile job is run for all e.List items. This process updates the
contribution e.List item data blocks and reaggregates all of the review e.List items.
In order to understand how No Data access settings affects memory use and calculation speed, it
is necessary to describe how the access settings are applied. The process is as follows:
● All access tables are resolved.
● Items which are entirely No Data for all cubes in the model are identified.
● Items are removed from dimensions where possible (see restrictions below).

As a rough guide, each e.List item is approximately 1 KB per item (this is where you have roughly
one user per e.List item). Each dimension item is between 100 and 250 bytes. The e.List item is
larger because it contains extra information.
How No Data Access Setting Affects Data Block Size
Creating Access Tables
Data blocks are used for persistent storage of the data in the model. The data block contains data
for each cube for a particular e.List item, and only includes items for which there is data in that
cube. The restrictions relating to cut-down dimensions that apply when working with the model
in memory do not affect the persistent data blocks. These are cut-down to the maximum extent
possible to reduce the data block size.
The data blocks are created during the reconciliation process.
Reducing the data block size affects download and upload speed (when opening the grid and when
saving or submitting) and can reduce network traffic. It also affects the speed of aggregation up the
e.List when contribution data is saved, and hence reduces the load on the run time server components.
Create access tables to determine the level of access that users have to cubes, saved selections, and
dimension items.
The access tables pane is divided up into the following areas:
● Cubes With Access Tables
Assign access levels to dimensions and saved selections either using the Administration Console,
or by importing simple access tables.
● Cubes Without Access Tables
Assign an access level to a whole cube, if it has no individual access tables.
● Assumption Cubes
Set access levels for the whole cube (you cannot create individual access tables for assumption
cubes).
Note: If you create an access table after you have imported data, the entire import queue is deleted.
Making changes to access tables, e.List items or saved selections that affect the pattern of no data
in a cube can also result in data loss, see "Changes to Access Tables That Cause a Reconcile Job
to Be Run" (p. 136) for more information.
Before you can set access levels, you must first have imported an e.List.
Steps
1. In the application's tree, click Development, Access Tables and Selections, and Access Tables.
2. You can do any of the following:
● Assign access levels to dimensions and saved selections. You can either create rule based
access tables using the Administration Console, or you can import access tables created in
external applications.
Chapter 8: Managing User Access to Data
Administration Guide 123

Chapter 8: Managing User Access to Data
Cubes With Access Tables
124 Contributor
● Assign an access level to a whole cube if it has no individual access tables. For more
information, see "Cubes Without Access Tables" (p. 126).
● Set access levels for the whole cube (you cannot create individual access tables for
assumption cubes). For more information, see "Assumption Cubes" (p. 126).
In the Cubes With Access Tables section you click the dimensions that you want to set access for,
then you click the cubes that this access level applies to. You can choose to make the access table
applicable to any or all these cubes by selecting the relevant cubes in Candidate Cubes.
You can choose to make the access table applicable to all or part of the e.List. If you click Include
e.List, you can select which parts of the e.List the access table is applicable to. If you do not include
this option, it will apply to all parts of the e.List.
The default value for cubes with access tables is write.
You can also import access tables, see "Importing Access Tables" (p. 126).
Steps to Create Access Tables
1. In the appropriate application tree, click Development, Access Tables and Selections, and then
Access Tables.
2. Select one or more dimensions in Available Dimensions.
To select more than one dimension, hold down the CTRL key and then click the dimensions.
The list of Candidate Cubes shows which cubes contain all the selected dimensions. If you have
selected more than one dimension, only those cubes that contain all these dimensions can be
selected. Note that the more dimensions you include in an access table, the bigger the access
table will be. Large access tables can slow the system down considerably, see Large Access
Tables for more information.
3. Select one or more cubes from the Candidate Cubes list. Normally you will apply an access
table to all candidate cubes.
4. Ensure that Create rule based access table is selected (this is the default).
5. Choose whether to include the e.List. The default is for the e.List not to be included meaning
that the access settings apply across the whole e.List.
Note: If you create access level rules with the e.List included, clear the Include e.List option
and save, then subsequently decide to include the e.List again, you must reenter any e.List
specific access settings.
6. Click Add. This adds your selection to the list of access tables.
Tip: In the access tables list, you can edit the name of the access table.
7. Select one or more of the rows that you have just added to the access tables list and click Edit.
The next step is to assign access to dimension items, or to saved selections. For more information,
see Exporting Access Tables.

After you have edited the access table, you should save. If there is data in the import data queue,
you will receive a warning that the import data queue will be deleted. You may also receive a
warning such as:
Saving these changes will require a reconcile job to run next time you Go to Production. Do
you want to continue?
Reconciliation ensures that the copy of the application that the user accesses on the Web is up
to date. If you click Yes, the changes are saved and when you run Go to Production, a recon-
ciliation job is created. If you click No, the changes to the access table pane are discarded.
Change the Cubes to Which an Access Table Applies
You can choose specific cubes to which you want the access tables to apply.
Steps
Editing Access Tables
1. Select the access table that you want to change.
2. Click the Cubes button.
3. Check those cubes you want the access table to apply to.
When you edit an access table, you set access levels for selections and for combinations of dimension
items.
To reach the access table editor, you must first create an access table. For more information, see
Creating Access Tables.
Steps
1. Select the access level, and then click the saved selection, or dimension items from each list,
and e.List items (if included).
2. In any one list of saved selections and dimension items, you can click either one saved selection,
or a combination of dimension items. Selecting applies a rule to all items in the
dimension or e.List.
3. Click Add to create the access rule.
4. Repeat until you have created all the rules for the access table.
These access rules are resolved in the order in which they were assigned. If more than one rule
is applied to an item, the last access rule assigned is given priority and will apply. Use the arrows
to change the order in which access rules apply. If no rules are set, an access level of Write
applies.
Warning
Once you have created access level rules for an access table, if you decide to remove or include the
e.List again, you will lose any rules that you have set for this table and will have to reset them. See
Rules for Access Tables for more information.
Chapter 8: Managing User Access to Data
Administration Guide 125

Chapter 8: Managing User Access to Data
Changes to Access Tables
If you edit access tables, and the change would make the memory usage of the model significantly
greater (for example, adding another dimension), you may find that, although the access table saves
correctly, the next time you open the Administration Console, it may fail to load properly. If this
happens, you can do the following:
Note that Reset Development to Production removes all changes made since the last time Go to
Production was run.
Steps
1. Check the log file. Click the Tools, Show Local Log File menu to see if it shows an "Out of
memory" message.
Cubes Without Access Tables
2. If this happens, you can work around it by clicking the Reset Development to Production button
in the toolbar and reapplying any changes that you had made.
The Cubes without Access Tables section allows you to set the access levels for whole cubes that
do not have any access tables defined for them. The default access level for a cube is Write.
See Rules for Access Tables for information on the access levels and priorities.
Steps
Assumption Cubes
1. In Access Tables, click in the appropriate Access Level cell.
2. Click a new value from the list.
If you set the global access level for cubes without access tables from Write to a different level,
such as Read, and then subsequently create and access table for this cube, See Cubes With
Access Tables, the global setting for the cube is reset to Write.
Any assumption cubes in the application are listed in the Assumption Cubes section. The default
access value for assumption cubes is Read, and the other available value is Hidden. You can change
the default access value.
Steps
Importing Access Tables
126 Contributor
1. Click in the appropriate Access Level cell.
2. Click either Read or Hidden from the list.
Assumption cubes contain data that is moved into the Contributor application when you run
the Go to Production process and when you synchronize. They do not contain the e.List.
You can import access tables that already exist into cubes. They can be in Excel worksheet, comma,
delimited, tab delimited, or custom delimited format.
For information on the format of access tables, see "Format of Imported Access Tables" (p. 127).

You can also automate the import of access tables. See "Import Access Table" (p. 206) for more
information.
Steps
1. Click Development, Access Tables and Selections, and Access Tables.
2. In the Access Tables pane, click one or more dimensions in Available Dimensions. The Candidate
Cubes list shows which cubes contain all the selected dimensions with no conflicting access
tables. If you have selected more than one dimension, only those cubes that contain all these
dimensions are selectable.
3. Select one or more cubes from the Candidate Cubes list. Normally, you apply an access table
to all candidate cubes.
4. Select Import access table, and Include e.List if required.
5. Click Add. Once you have clicked the Add button, you cannot change whether a table is rule
based or imported. There is a check mark to indicate if you have selected Import access table
in the access table grid.
6. Click Import. The Import Access Table dialog box is displayed.
Note: You can use this dialog box to set the base access level without importing an access table.
7. Enter the file name and location for the access table import file.
8. Select the First row contains column headers box if required.
9. Select the file format. If the file format is Excel Worksheet, enter the name of the worksheet
containing the access table.
10. Select the Import option.
11. Delete undefined items: If an access table file has previously been imported for the access table
and you are importing a new one, existing settings are updated with the new settings specified,
and any previous settings that do not exist in the new file are kept, or if Delete undefined items
is checked, are deleted.
12. Select the Base access level. This is the default level that is applied to any undefined items. No
Data is the default access level. See "Access Level Definitions" (p. 121) for more information.
13. Click OK.
14. To view the access table, click View. You can print this file and save to file. You can also export
Format of Imported Access Tables
the access table, see "Exporting Access Tables" (p. 129).
The Imported access tables file can be in any of the following formats: Excel worksheet, comma
delimited, tab delimited, custom delimited.
Chapter 8: Managing User Access to Data
● A column for every dimension that the access table will apply to (mandatory). The names of
dimension items must be identical in spelling and case to the way they are in the Analyst model.
Administration Guide 127

Chapter 8: Managing User Access to Data
● A column containing e.List items. If omitted, the access level applies to the whole e.List.
● A column containing access levels (optional). The following access levels can be set Hidden,
Read, Write, No Data (these are not case sensitive). If omitted, a default of Write will apply.
It is important to note that you cannot import saved selections or rule based access tables. Each
line of the access table (barring the headings, if used) contains the following information:
dimension item name (from dimension a) [tab] dimension item name (from dimension b) [tab] e.List
item (if e.List included) [tab] AccessLevel
Column Order
The required order for the dimension columns in an access table import file with no column headers
is the same as the dimension order of the access table. You can see this in the access table setup
pane:
This shows the order of dimensions as: Versions and Channels. In this case, the third column would
be the e.List, and the fourth column would contain the access levels.
If the import file contains column headings, the columns can be in any order.
Column Headings
The use of column headings in the import file is optional. If column headings are used they should
be in the following format:
Name of the Dimension
This must be the same spelling
and case as in the Analyst
model.
Name of e.List
This must be the same spelling
and case as in the Analyst
model.
Column headings are the first row in the file.
Viewing Imported Access Tables
128 Contributor
You can view access tables that you have imported.
AccessLevel
As shown. Default is Write.
You cannot edit an imported access table within the Administration Console. To make changes,
you should edit the source file and import again.
Steps
1. Click Development, Access Tables and Selections, and Access Tables) to open the access tables
pane.
2. Click the access table that you want to view and click View.

Exporting Access Tables
3. The View button is not enabled for access tables created in the Administration Console (rule-
based tables). To view rule-based access tables, click Edit.
You can export access tables in a format that you will be able to import. You will be able to export
both simple and rule-based access tables. Once you have exported a rule-based access table, you
can import it again, but it will be imported as a simple access table that you will not be able to edit
in the Administration Console.
Steps
1. Click Development, Access Tables and Selections, Access Table), and click the access table to
be exported.
2. Click Export.
3. Enter or browse for a file location and file name. You can export to a text file, tab separated
format.
Large Access Tables
4. If you want to include column headings, select Include column headings.
5. Click OK to create the file and Close to close the dialog box.
It is important to use small access tables where possible rather than single multi-dimensional access
tables. In general it is far easier to understand and maintain several small access tables than a single
large one. Replacing a large access table with small access tables may improve the performance of
the Administration Console. However, in some cases, access to items in one dimension cannot be
defined without reference to the items of another dimension, and so a multi-dimensional access
table must be used.
The following issues are associated with using large access tables:
● They can cause substantial performance problems in the Administration Console.
● They can increase the physical size of the cut-down model so that the benefit of using cut-down
models is lost. This is because the access table needs to be resolved.
● If cut-down models are not used, resolving access tables on client machines can cause perform-
ance problems.
Administration Console Performance Issues
Chapter 8: Managing User Access to Data
When you perform an action in the Administration Console that makes use of the access tables,
the system resolves the access tables in order to determine what access level applies to each cell,
and which cells contain data. A large access table can slow down the system considerably. This is
because a check is made whenever you load the development application in the Administration
Console, and whenever you save, to see whether the pattern of access has changed to or from No
Data. This check is made primarily to determine whether a reconciliation job is required on running
Go to Production, and which e.List items must be reconciled. For example, if you are importing
Administration Guide 129

Chapter 8: Managing User Access to Data
data, a check is run to see if any changes have been made to the access tables, saved selections, or
the e.List that result in a different pattern of No Data cells. Another example is when you run Go
to Production and the cut-down models job is run (if set on). The cut-down models process uses
the information from access tables to determine what information each user will get.
Memory Needed to Resolve an Access Table
The amount of memory needed to resolve an access table is determined by the product of the
number of items in each dimension multiplied by four bytes, and so the greater the number of
dimensions you include in an access table, the greater the memory required. If you use more access
tables with fewer dimensions in each, the memory requirements are reduced considerably (this is
demonstrated in Example 1). If the memory needed to resolve an access table is more than two GB
it will fail on the server. This is because two GB is the maximum memory that can be addressed by
the operating system. For example, an access table that includes an e.List of 1500, a products list
of 1500 and 250 channels would exceed this limit. (1500 x 1500 x 250 x4 = 2,250,000,000).
Impact of Large Access Tables on Cut-down Models
Examples
130 Contributor
Using large access tables can have a negative impact on the physical size of the individual cut-down
model definitions that are downloaded to the client computer.
The cut-down model definition contains the information about the individual e.List item or review
e.List item and its immediate children. It also contains the relevant part of the resolved access table
and is cut-down to the necessary D-List items needed to control access. In the example shown below,
the resolved access table will contain the products list of 1500 items and the channel with 250 items.
Multiplied by four bytes, this may increase the size of the cut-down model definition by as much
as 1.5 Mb (this could be less, for example, if only some of the channels apply).
These examples set access to the following dimensions in a Revenue Plan cube:
The e.List (named Stores) contains these saved selections:
● High street
● Superstores
● Telesales Centers
These saved selections are subsets of the total (All). There are 1200 items in Stores.
Channels contains these saved selections:
● Retail
● Discount
● Mail Order
These saved selections are subsets of the total (All). There are 12 items in Channels.
Products contains these saved selections:
● Sanders

● Drills
Note that not all items are included in these saved selections. There are 400 items in Products.
Example 1
This example shows two different ways of setting access where available Channels vary by store
and product selection is the same for all stores and channels. Tables A and B achieve this in the
most efficient way. See the following calculations:
The size of Access Table A is:
● 12 (Channels) x 1200 (Stores) x 4 (bytes) = 57.6 KB
The size of Access Table B is:
● 400 (Products) x 4 (bytes) = 1.6 KB
The total size of the two access tables is 59.2 KB.
The size of the Access Table C is:
● 400 x 12 x 1200 x 4 = 23.04 MB
This means that Access Table C takes 22.98 MB more memory to resolve than tables A and B
together.
Using two separate access tables is also easier to maintain. For example, if High Street stores started
selling through the Mail order channel, using two tables, you just add one line to Access Table A.
But for Access Table C, you must add three lines.
A. Access Table for Channels
No Data
Write
Write
Write
Write
Channel
All
Retail
Retail
B. Access Tables for Products
Write
Read
Discount
Mail order
Product
All
Sanders
Chapter 8: Managing User Access to Data
Store
All
High Street
Superstores
Superstores
Telesales
Administration Guide 131

Chapter 8: Managing User Access to Data
132 Contributor
Hidden
Product
Drills
C. Combined Access Table (Not Recommended)
No Data
Write
Read
Hidden
Write
Read
Hidden
Write
Read
Hidden
Write
Read
Hidden
Example 2
Product
All
All
Sanders
Drills
All
Sanders
Drills
All
Sanders
Drills
All
Sanders
Drills
Channel
All
Retail
Retail
Retail
Retail
Retail
Retail
Discount
Discount
Discount
Mail order
Mail order
Mail order
Store
All
High Street
High Street
High Street
Superstore
Superstore
Superstore
Superstore
Superstore
Superstore
Telesales
Telesales
Telesales
This shows two different ways of setting access where products vary by store and channels vary by
store.
In this case, the e.List (Store) must be included in both access tables. Superstores can write to drills.
Note that it is not necessary to put the line Write, Drills (Retail/Discount), Superstores into the
access table, you can leave this out. This was added for illustrative purposes.
The size of Access Table D is:
● 12 (Channels) x 1200 (Stores) x 4 (bytes) = 57.6 KB
The size of Access Table E is:

● 400 (Products) x 1200 (Stores) x 4 (bytes) = 1.92 MB
The size of the Access Table F is:
● 400 x 12 x 1200 x 4 = 23.04 MB
So even with the additional dimension in Access Table E, the combined total of Tables D and E of
1.98 MB is still 21.06 MB less than Access Table F.
Note that although tables D and E are separate, they interact. The channels that are shown are
dependent on which product is viewed, and the e.List item that is selected.
Access Tables for Channels
No Data
Write
Write
Write
Write
Access Tables for Products
No Data
Write
Read
Hidden
Write
Read
Hidden
Write
Read
Channel
All
Retail
Retail
Discount
Mail order
Products
All
All
Sanders
Drills
All
Sanders
Drills
All
Sanders
Chapter 8: Managing User Access to Data
Store
All
High Street
Superstores
Superstores
Telesales
Store
All
High Street
High Street
High Street
Telesales
Telesales
Telesales
Superstores
Superstores
Administration Guide 133

Chapter 8: Managing User Access to Data
134 Contributor
Write
Products
Drills
Combined Access Tables (Not Recommended)
No Data
Write
Read
Hidden
Write
Read
Write
Write
Read
Write
Write
Read
Hidden
Example 3
Product
All
All
Sanders
Drills
All
Sanders
Drills
All
Sanders
Drills
All
Sanders
Drills
Channel
All
Retail
Retail
Retail
Retail
Retail
Retail
Discount
Discount
Discount
Mail order
Mail order
Mail order
Store
Superstores
In this example, the product selection varies by Store and Channel.
Superstores can write to sanders for the discount channel only.
An Access Table that Cannot be Split
No Data
Write
Products
All
All
Channels
All
Retail
Store
All
High Street
High Street
High Street
Superstore
Superstore
Superstore
Superstore
Superstore
Superstore
Telesales
Telesales
Telesales
Store
All
High Street

Read
Hidden
Write
Read
Hidden
Write
Read
Hidden
Write
Read
Write
Products
Sanders
Drills
All
Sanders
Drills
All
Sanders
Drills
All
Sanders
Drills
Channels
Retail
Retail
Retail
Retail
Retail
Mail Order
Mail Order
Mail Order
Discount
Discount
Discount
Store
High Street
High Street
Superstores
Superstores
Superstores
Telesales
Telesales
Telesales
Superstores
Superstores
Superstores
You do not need to include the Write, Drills, Discount, Superstores line. This is included for illus-
trative purposes.
Multiple Access Tables
Example
No two access tables that control the same dimension can be applied to the same cube, but you can
have multiple access tables using different dimensions that apply to the same cube. Where this is
the case, a planner will get the lowest level of access amongst all the access tables.
In the Versions dimension, item Budget version 1 is writeable for the planner and item Budget version
2 is read-only. In the Expenses dimension, the item Telephone is writeable and the item Donations
is hidden. The planner will get the following resolved access:
Telephone
Donations
Budget version 1
Write
Hidden
Chapter 8: Managing User Access to Data
Budget version 2
Read
Hidden
When access to the cells of a cube needs to be controlled using more than one dimension (as in the
example above), you must decide whether to use multiple access tables (one for each dimension),
Administration Guide 135

Chapter 8: Managing User Access to Data
or one access table using all the dimensions. You should choose multiple access tables (one for each
dimension) wherever possible (as in the example above). In general this will be much easier to
understand and maintain. You should only use a multi-dimensional access table in circumstances
when access to items in one dimension cannot be defined without reference to the items of another
dimension.
Conflicting access tables are not allowed. You cannot apply multiple access tables to one cube using
the same dimension. For example, if you have applied an access table for the dimension Months to
a cube, you cannot apply another access table using Months, nor one that uses Months and Versions,
and so on. After choosing the dimension for an access table, your choice of cubes which the access
table can be applied to is limited to those cubes that contain the chosen dimensions.
Changes to Access Tables That Cause a Reconcile Job to Be Run
Changes to access tables may or may not cause a reconcile job to be run, depending on whether
they impact the pattern of No Data cells in a model.
When access tables are changed, the system determines whether there is any impact on the pattern
of No Data cells in a model. If the system determines that there is no impact, then no reconciliation
takes place.
If however the system determines that there is an impact, then all e.List items must be reconciled.
All contribution e.List item data blocks are updated, and all review e.List items are re-aggregated.
If an access table definition is changed, the system compares the resolved pattern of No Data cells
before and after the changes. If the pattern of No Data cells is not identical, then reconciliation of
all e.List items is required. If the pattern of No Data cells is identical, then no reconciliation is
required.
This comparison is only made for e.List items shared by the development application and the current
production application. So, the addition or deletion of e.List items in itself will not require recon-
ciliation of all e.List items.
If an entire access table is added or deleted, then reconciliation of all e.List items is required.
If the set of cubes an access table applies to is changed, then reconciliation of all e.List items is
required.
Changes to the e.List which affect saved selections used in access tables can also cause a reconciliation
job to run. For more information, see "The Effect of Changes to the e.List on Reconciliation" (p. 104).
Changes to Access Tables and Saved Selections and the Effect on Reconciliation
136 Contributor
When access tables are changed, the system determines whether there is any impact on the pattern
of No Data cells in a model.
If an impact is determined, all e.List items are reconciled. Access tables can be changed indirectly
by changing a saved selection used by an access table, or by making certain changes to the e.List if
the e.List is used in a saved selection used by an access table. Note that changes made to other
dimensions may impact access tables via saved selections, but these changes are introduced via
synchronize which always requires full reconciliation.
The cases where changes to the e.List affect saved selections are:

● A saved selection on the e.List uses Filter and existing contribution items are renamed in the
e.List.
● A saved selection on the e.List uses Enlarge (of a review e.List item) and existing contribution
items are moved between review items in the e.List.
This only applies to e.List items shared by the development application and the current production
application. The addition or deletion of e.List items in itself will not require reconciliation of all
e.List items.
Access Tables and Import Data
The import queue can be deleted in two ways. It will be deleted if any changes are made to existing
saved selections or e.Lists that result in a different pattern of No Data cells for contribution e.List
items that are common to both the development and production applications. It will also be deleted
if any access tables are created after data has been imported.
Access Levels and Contributor Data Entry
Force to Zero
With the exception of the No Data access setting, access settings affect only planner data entry.
They do not affect D-Links, import or data to be published:
● D-Links may target Hidden or Read-only cells.
● Import may target Hidden or Read-only cells. All valid data present in an ASCII file is imported
into a cube. To limit the selection of cells targeted you should cut-down the ASCII file to contain
only the required data. Data in the source ASCII file that does not match an item in a cube is
not imported and is reported as an error. Import cannot target formula cells in a cube. Import
data should not target No Data cells.
● Published data can include cells that are marked as Hidden, Read-only, or Writeable.
In Analyst, the calculation option Force to Zero forces calculations in other dimensions to return
zero. Contributor interprets this option differently, effectively as Force to No Data. This can cause
items to disappear from the Contributor grid.
If you do not want such items to disappear in Contributor, you should remove the Force to Zero
setting in Analyst.
Reviewer Access Levels
Chapter 8: Managing User Access to Data
Access for reviewers cannot be defined explicitly. Access for any review e.List item is automatically
derived from access settings applied to the planners below the particular review e.List item.
Administration Guide 137

Chapter 8: Managing User Access to Data
Cut-down Models
Cut-down models are customized copies of the master Contributor model definition that have been
cut-down to include only the specific elements required for a particular e.List item. Note that the
e.List is also cut-down.
Cut-down models can substantially reduce the size of the model that the Web client has to download
when there are large dimensions containing hundreds or thousands of items, of which only a few
are required for each planner.
However, the cut-down model process significantly increases the amount of time it takes to run the
Go to Production process.
The process of creating the cut-down model for a particular e.List item is as follows:
● All access tables are resolved.
● Items which are entirely No Data for all cubes in the model are identified.
● Items are removed from dimensions where possible, for more information, see "Restrictions
to Cutting Down Dimensions" (p. 140).
● The cut-down model definition is saved in the datastore.
When Does the Cut-down Models Process Happen?
Limitations
138 Contributor
The cut-down model process is triggered in the following circumstances:
● The first time Go to Production is run and one of the cut-down model options have been
selected.
● Changes have been saved to the Contributor model, one of the cut-down model options have
been selected, and Go to Production is run.
Cut-down models are not created if no changes have been saved to the Contributor model. A change
is any action which allows you to click Save after completing. Changes to existing translations are
exceptions to this rule. If the only change you make is to an existing translation, the cut-down
model process will not be triggered.
Importing data does not change the Contributor model. This means that you can import data and
run the Go to Production process without causing the cut-down model process to be triggered.
When changes are saved to the Contributor model, the package GUID in the model (a unique
identifier that is used to reference objects) is also changed, causing cut-down models jobs to be
created. If no changes have been made, the GUID does not change so there is no need for cut-down
models to be run.
The cut-down model process can cause the runtime load on the server to be adversely affected.
Without cut-down models there is a single model definition which can be cached in memory on the
server, reducing the number of calls to the datastore. When cut-down model definitions are used,
there are too many of them to cache in memory on the server. As a result, the particular model
definition must be retrieved from the datastore every time.

Even if cut-down models are not being used, the same process of cutting down the dimensions
happens anyway when the model definition is loaded. The benefits of using No Data access settings
to reduce memory requirements and decrease block size apply regardless of whether cut-down
models are being used. See "Restrictions to Cutting Down Dimensions" (p. 140) for more information.
Cut-down Model Options
The following options are available for cut-down models:
● No cut-down models (default).
● For each aggregate e.List item (p. 139).
● For every e.List item (p. 139).
Create Cut-down Model Definition for Each Aggregate e.List Item (Review Level Model Definition)
In review-level model definitions, separate model definitions are produced for each review e.List
item and its immediate children. In this case all contribution e.List items below a particular review
item use the same model definition.
Because review-level model definitions require considerably fewer model definitions, they take less
time to produce or recreate. They should be used when the selections are not small subsets of those
required at parent level, or when it would take too long to produce or recreate the planner-specific
model definitions - typically with e.Lists with thousands of items. This option is a compromise
between no cut-down models and fully cut-down models.
Create Cut-down Model Definition for Every e.List Item
In planner-specific model definitions, all required model definitions are individually produced:
● One for each contribution e.List item.
● One for each review e.List item with its immediate children (extra model definitions for the
individual review e.List items are not required).
● One for each multi-e.List item "my contributions" view (where a planner has responsibility for
multiple e.List items). Model definitions are not produced where a planner owns all the children
of a particular review e.List item. The review and children model definition will be used instead.
The benefit of creating a cut-down model definition for every e.List item is that performance is
optimized for each planner. But it may take some time to produce or recreate the model definitions.
This option should be used when the appropriate selections for the children of one review e.List
item are small subsets of the selections required for the parent review e.List item.
Cut-down Models and Translation
A cut-down model is only created for the base language. When a user wants to view their slice of
the Contributor model in the Web client, the language that they see is determined at the point when
they ask to see the model. This means that the language can be changed without having to run Go
to Production.
Chapter 8: Managing User Access to Data
Administration Guide 139

Chapter 8: Managing User Access to Data
Cut-down Models and Access Tables
When a planner opens the grid for a Contributor application the Web client receives two pieces of
data from the server. The first is the model definition (also referred to as the XML package) and
the second is the data block that contains the values that will populate the grid. Together these are
referred to as the model.
Access tables control which cells in a model are Writeable, Read-only, Hidden, or contain No Data.
Cut-down models are customized copies of the master model definition that have been cut-down
to include only the specific elements required for a particular e.List item.
Access tables must be carefully considered when setting up cut-down models. Potentially, the
overhead in terms of model size and memory usage for using access tables can be higher than the
benefit gained from using cut-down models.
When models are large, you should use access tables along with cut-down models so that the size
of the model to be downloaded to each client is reduced.
Cut-down model options are set in the Application Options pane, see "Change Application
Options" (p. 74).
Restrictions to Cutting Down Dimensions
140 Contributor
There are restrictions involved when cutting down dimensions.
Certain types of dimension are never cut down:
● Timescales (cutting down timescales would affect the result of BiF calculations).
● The data dimension of the source cube for an accumulation link (that is, the dimension which
contains D-List format items that are treated as if they were dimensions of the source cube).
● The data dimension of the target cube for a lookup link (that is, the dimension which contains
D-List format items that are treated as dimensions of the target cube).
● A dimension used in an assumption cube.
● A dimension that is also used as a D-List format.
Certain items will not be removed:
● Items are not removed if they are used in a calculation that is not a simple sum, unless the cal-
culation itself is also being removed.
● Items that are the weighting for a weighted average are not removed unless the average is also
removed.
The level of cut-down applied per dimension is the resolved level across all cubes. This is why it is
impossible to cut down a dimension that is used in both an assumption cube and a contribution
cube, because the entire dimension is required for the assumption cube. Where the same dimension
occurs in two or more contribution cubes with different access tables, it will only be cut-down to
remove items that are not required in any cube. As a result, there are cases where dimensions are
not cut-down as much as might be expected, resulting in greater memory usage. However, there
are ways in which to structure the model to avoid this situation.

Example 1
Example 2
Cutting Down a D-List to No Data
If a D-List is used by multiple cubes but is cut down to no data in just one of them, then the cube
with no data will be hidden from users of that e.List, but the size of the dimension will be the full
size of the D-List. Therefore, the size of a D-List for any e.List item will always be that size, even
if set as No Data.
For example, if you have a model where:
● cube 1 contains a dimensions e.List, products, customers, and timescale
● cube 2 contains e.List customers and timescale
● cube 3 contains e.List products and timescale
If you create an access table on customers and products and include the e.List and then add a line
to make all products and customers No Data for just one of the e.List items, it will apply to cube
1, as that is the only cube that has both products and customers.
If you then log on to the grid as the user of the e.List item, you will not see cube 1 because it will
be hidden. But the size of the dimension will be unchanged because the customer list is needed in
full for cube 2 and products list is needed in full for cube 3.
If you have a dimension that can not be cut down because it is used by an assumption cube, you
could create an identical dimension to substitute in to the assumption cube leaving the dimension
in other contribution cubes to be cut down.
If the assumption cube is causing the problem, an alternative is to add the e.List to the assumption
cube and apply access settings to this cube so that the dimension can be cut down.
Estimating Model and Data Block Size
The size of the model definition XML is primarily dependent on the total number of items in the
dimensions of the model, and is not dependent on the number of data cells. The master model
definition can be between 100 bytes and 250 bytes per dimension item. e.List items are generally
larger as they contain more information--approximately 1 KB if there is roughly one user per e.List
item. Typically most of the other information in a model definition is small in relation to the
dimension items. The only exception is that the data for assumption cubes is stored in the model--
approximately 10 bytes per data cell. If the assumption cubes are large, allow for this when estim-
ating the model XML size.
If cut-down models are used, the same rule still applies for each cut-down model, but the number
of items in the dimensions will be reduced as a result of access tables. Even without access tables
the e.List will be cut-down.
Chapter 8: Managing User Access to Data
The size of the XML data block for a particular e.List item is proportional to the number of dense
data cells in all the cubes for that item. However, this is very hard to estimate, because it depends
on the proportion of cells that contain non-zero data, and also the pattern of how these cells are
spread through the cube. Also certain data values take less space than others (small integers are
Administration Guide 141

Chapter 8: Managing User Access to Data
packed more efficiently than large integers or floating point values). As an approximate upper
bound, a data block should not be much larger than 16 bytes per cell in all the cubes.
Please note these are rough estimates.
Cut-down Model Example
142 Contributor
In the e.List shown, Total and Div1 to Div10 are review e.List items, and CC1a to CC10j are con-
tribution e.List items (all owned by different users):
The model is an Employee Plan cube with an Employees dimension. Each cost center (CC) has 100
of its own employees with no access to other employees. You would use an access table to give each
CC write access to the appropriate 100 employees, with no data access to the rest.
With no cut-down models, each planner will receive a model definition including a 10,000-item
employee list, which is large in size (approximately 2.5 MB). Only one model definition needs to
be produced and updated.
With planner-specific model definitions, each planner’s model definition will contain only the
required 100 items from the Employees dimension (approximately 25KB). Each dimension item is
around 250 bytes. One hundred and eleven model definitions must be produced and updated.
With review-level model definitions, the dimension definition downloaded to each planner will
contain 1,000 items--thus this element of the model definition will be ten times larger than it needs
to be, but still ten times smaller than the full version (approximately 250kb). Eleven model definitions
must be produced and updated.
To decide which cut-down method to use, consider these factors:
● The application structure itself.
● Whether bandwidth is an issue (are there many dial-up connections?)
● Time taken to produce and re-create the cut-down models.
● Number of e.List items.
● e.List hierarchy, for example, with review-level model definitions it may be sensible to reduce
the number of contribution e.List items per review e.List items by introducing dummy review
e.List items to reduce the size of the model definitions.

Chapter 9: Managing Data
The following types of data can be imported into and exported from IBM Cognos 8 Planning -
Contributor.
Type of data
Data in other Contributor
applications and cubes
Data in other Contributor
applications and cubes
Data in Contributor applic-
ations, Analyst libraries,
macros, and administration
links
Text files
IBM Cognos 8 Business
intelligence data sources,
including SAP BW
Text files and Contributor
cubes
Data in Analyst
Function and target version
Administration links (p. 147) in the Administration Console
Targets either the production or development application
System links (p. 144) in the Administration Console. Executed in
the Web client using Get Data.
Targets the production application
Export a Contributor model or model with data, administration
links, macros, and Analyst libraries and import them into a target
environment or to IBM Cognos Resource Center (p. 170)
Targets the development, test, or production applications
Import Data (p. 173) in the Administration Console
Targets the development application
Import from IBM Cognos Package using Administration links
(p. 147)
Targets the development application
Local links in the Web client.
Targets the production application
Analyst>Contributor links in Analyst. See Analyst User Guide
Targets either the production of development application
If you are moving data between Contributor cubes and not making model changes, use an admin-
istration link to move data into the production application. The data is processed using an activate
process, you do not have to run Go to Production. Note that there is no option to back up the
datastore when targeting the production application. You can target only the development applic-
ation if you are importing data from IBM Cognos 8 Packages.
Administrators can also set up links that are run from a Web client session enabling Web client
users to move data between a cube in a source application and a cube in a target application. For
more information, see "Administration and System Links" (p. 144).
Administration Guide 143

Chapter 9: Managing Data
When you import data into a Contributor application, the data is first put into an import queue.
There are two import queues, one for the development version of an application and one for the
production version of an application. The import queues are independent of each other and contain
the data in import blocks that are applied to an e.List item during a reconcile job.
For each e.List item in an application, there is a model import block. Prior to being moved into the
cube by a reconcile job (p. 54), the data from importing data, administration links, Analyst to
Contributor, or Contributor to Contributor links, is placed into this model import block. For links
that target the development application, the reconcile job is created during the Go to Production
process. For links that target the production application, an activate process creates a reconcile job.
Important: Be aware that if two reconcile jobs are run while users are working offline, the users
will be unable to bring the data online. See "Editor Lagging " (p. 255) for more information.
Because you can have multiple cube import blocks per cube, you can run administration links and
Analyst to Contributor links, as well as import data, concurrently.
Note that a model import block is represented by a row in the import queue table in the application
datastore. An individual cube import block cannot be seen in the datastore.
Understanding Administration, System, and Local Links
144 Contributor
Administrators can move data between Contributor cubes and applications using administration
and system links. Administrators can also import data from IBM Cognos 8 packages using admin-
istration links. Web client users can move data between Contributor cubes using local links.
Administration and System Links
Administrators can create and run administration links to move large amounts of data between a
source application and a target application and from an IBM Cognos 8 package to a Contributor
application.
Administrators can create system links to allow users to move small amounts of data between a
cube in a source application and a cube in a target application. These links are run from a Web
client session by the Web client user.
Note: For Classic Contributor Web Client users, the Get Data extension must be configured before
you can create a system link. For more information about configuring the Get Data extensions, see
"Configure Classic Client Extensions" (p. 301).
The difference between administration and system links is described in the following table.
Administration Links
Run by the administrator in the Contributor
Administration Console, and by using macros.
Designed to move large amounts of data and
can be scheduled.
System Links
Run on the Contributor Web client by the
Contributor application user (but created by
the administrator in the Contributor Adminis-
tration Console).
Designed to move small amounts of data on an
ad-hoc basis.

Administration Links
Run on the job servers.
Stored in the Content Manager datastore.
When moving data between Contributor
applications, can contain multiple elements (sub-
links) enabling a single link to have many cubes
as the source and target.
Can map an e.List dimension to a non-e.List
dimension, enabling you to move data between
applications that do not share an e.List.
Can run a link to a locked e.List item.
When moving data between Contributor
applications, can be tuned for optimal perform-
ance.
Can be sourced from IBM Cognos Packages.
Local Links
System Links
Run on the Web client computer.
Stored with the target application.
Can contain only one element, and as a result
can contain only one source and target cube.
Can only map an e.List to an e.List dimension.
Cannot run a link to a locked e.List item.
Cannot be tuned for optimal performance.
Cannot be sourced from IBM Cognos Packages.
Local links allow Web client users to load data into the Contributor application from external data
sources, and from the active Contributor grid. You create and run local links in the Web client
using Get Data. These are similar to system links. For best performance, we recommend that users
import into one e.List item at a time from external sources.
Local links are similar to system links, except for the following differences:
● Local links are created in the Web client, and not the Contributor Administration Console.
● Local links can be used to import data from external data sources.
● In local links, users can only import data from tabs in the active Contributor grid (system links
can import data from source cubes to which the user has no access rights).
Using Links to Move Data Between Cubes and Applications
The kind of link you use depends on your role and what you want to do.
Web client users (planners) can move data into the Web client from external sources, or from the
active Contributor grid, using local links. For best performance, we recommend that users import
data into one e.List item at a time from external sources. Web client users can also move data
between cubes for one e.List item at a time, using system links created by the administrator.
Note: For Classic Contributor Web Client Users, the Get Data extension "Configure Classic Client
Extensions" (p. 301) must be configured before users can create a local link.
Chapter 9: Managing Data
Administration Guide 145

Chapter 9: Managing Data
Administrators move data from one production application to another, or to development applica-
tions by using administration links. The administration link process uses the job system and so
enables you to move large amounts of data. It is quicker to move data into the production application
if you have no model changes to make. This is because if you move data into the development
application, you must run Go to Production before the data is available to the Web client.
You can copy commentary between applications using administration, system, or local links. After
you run a link that includes commentary, annotation or attached documents, the target will have
the same value and commentary as the source. This means that commentary in the target is removed
if there is no commentary in the source. If you target a cell with more than one source cell, it will
contain the aggregated value and the commentary from all the source cells. If you select only one
type of commentary in the link, then the other type of commentary is not affected by running the
link. You will not have multiple copies of commentary in target cells if you rerun the link.
If you run more than one link to the same application, and the same cell is targeted, the most recent
value is returned.
You can import local links from Contributor for Microsoft Excel or the Classic Contributor Web
Client or export links into those tools. Local links that you want to import and export between the
Classic Contributor Client or Contributor for Microsoft Excel and the Contribuor Web Client must
be saved as link definition files (*.cld). You can save the link as XML if you are importing and
exporting links using the Contributor Web Client.
Administrators can also move smaller amounts of information from Analyst to Contributor using
Analyst >Contributor links. This process does not use the job system. We recommend that you use
the @SliceUpdate macro to split one large link (across the entire e.List) into smaller links that deal
with smaller numbers of e.List items at a time. A slice update sample is available on the IBM Cognos
Resource Center Web site.
For more information, see the IBM Cognos 8 Planning - Analyst User Guide.
Using Links in Model Design
146 Contributor
If you are designing new models, you can use administration and system links to improve perform-
ance and make security maintenance easier.
Instead of creating one large model targeted at many Web client users and then controlling what
they can see through access tables, you can create several smaller models, each targeted at a smaller
specific user group, and link the models together.
Smaller models mean there is less need for access tables to control what users see. Go to Production
times are typically faster because you can have a shorter e.List. The number of cut-down models
can also be reduced, shortening the processing time.
The following examples show how you can use links in your model design.
Cascaded Models
Using administration links, you can create several small models that contain a high level of detail,
targeted at regional managers, and roll them up into a larger application with less detail so that the
top executives see only the numbers that they are interested in.
For example, you can have America, Asia, and Europe models rolling up into a Corporate model.

Matrix Management
Using administration links, you can create models that allow data to roll up both on a regional and
departmental basis, with approvals from both organization structures.
For example, you can have a Company model where Human Resources reports into Country, and
this can be linked into a Corporate model where Country reports into Human Resources.
Enhanced Security
Administration links allow you to separate cubes into applications by purpose. For example, you
can have a sales forecasting application, a travel planning application, and a salary planning
application. This separation of duty can improve security maintenance. An application containing
a salary plan model may require many access tables to specify who can view the cube, you can
simplify the cube by separating the access tables from the cube.
Administration Links
An administrator can use administration links to copy data between Contributor applications
without having to publish data first. You can also use administration links to import data from
IBM Cognos 8 data sources such as Oracle data stores, SQL Server data stores, SAP BW, or IBM
Cognos TM1. If importing from IBM Cognos 8 data sources, you must first create a Framework
Manager model and publish it as a package to IBM Cognos Connection. For more information,
see "Importing Data from IBM Cognos 8 Data Sources" (p. 164).
If you are importing data from a Contributor application, you must have sufficient access rights to
select applications as the source and target of a link. If you are importing from IBM Cognos 8 data
sources, you must have the rights to select applications as the target of a link, and be able to access
the source package in IBM Cognos Connection. For more information, see "Configuring Access to
the Contributor Administration Console" (p. 38). If you have appropriate rights, you can secure
the ability to create, edit, execute, delete, import, and export administration links. You can also
secure previously created administration links (administration link instances).
Because data can be moved around easily, you can create smaller applications. Smaller applications
can improve performance because shorter e.Lists have quicker reconciliation times. Additionally,
smaller applications usually do not need as many access tables and cut-down models, so the time
taken to run Go to Production is reduced. You can tune administration links for optimal perform-
ance. For more information, see "Tuning Administration Links" (p. 158). For more information see
"Cut-down Models and Access Tables" (p. 140).
The source application must be a production application, which means that Go to Production must
be run at least once. Also, all e.List items in the source application must be reconciled, otherwise
the link will not run. The target application can be either the production application or the devel-
opment application. An e.List must be defined. You can map an e.List dimension to a non e.List
dimension to move data between applications that do not share an e.List. This is not possible in a
system link.
Chapter 9: Managing Data
Administration links are similar to D-Links defined between Analyst D-Cubes, except that look-up
links, and Fill, Add, and Subtract modes are not supported. Administration links are also similar
to system links. Administrators set up system links between applications that can be run on the
Web client by end-users using Get Data. System links also have to have a source e.List mapped to
Administration Guide 147

Chapter 9: Managing Data
148 Contributor
a target e.List. Unlike administration links, a single system link can run from only one source cube
in one application to one target cube in one application. You can, however, set up multiple system
links.
Administrators set up a series of elements that define sub-links from the production versions of
applications to either the development or production versions of target applications.
If the elements are grouped together into a single link so they can be run at the same time, you can
move data simultaneously between multiple applications. For example, you may want to move data
between the following applications:
● Sales > Profit and Loss
● Marketing > Profit and Loss
● Personnel > Profit and Loss
Administration links do not run unless one or more Job servers are monitoring the Planning Content
Store. For information about adding the Planning Content Store to a Job server, see "Add Applica-
tions and Other Objects to a Job Server Cluster" (p. 57).
Order of Link Elements
The order of elements in a link is important if individual elements in a link target the same applic-
ation, cube, and e.List item. The order matters because of the way the data load works. When the
administration link is run, each element of the link creates an individual cube import block for each
e.List item that it is targeting.
For example, if three link elements all target two e.List items in the Expenses cube in the Sales
application, six cube import blocks are created.
● When link element one is run, two cube import blocks are created, one for each e.List item.
● When link element two is run, it targets the same e.List items, and overlaps some of the cells
targeted by link element one. A further two cube import blocks are created.
● When link element three is run, it also targets the same e.List items, and two cube import blocks
are created.
Any cells that are updated by link element three that overlap elements two and one take the value
from element three. Each e.List item in the target application can have only one Model Import
Block (MIB) per application state type. The MIBs are stored in the import queue. There could be
one for development and one for production. Each MIB can hold many cube import blocks (CIB).
CIBs are inserted into the MIB in chronological order. There is no specific precedence related to
the source of the data. Each link element has its own CIB, as does each Analyst link, plus another
CIB for the relational import.
Note: Where multiple link elements exist in a link, the CIBs for those links will be in the order that
the link elements are defined in the link.

Link Mode
Administration links run in Substitute mode. This means that data in cells in the target area of the
D-Cube are replaced by the transferred data. If no data is found in the source for a particular cell,
the data in that cell is left unchanged.
If data is imported into a read-only cell that is a target of a D-Link, the D-Link will override the
current import value.
Link Order
The order in which you run links is important. For example, if you run the Analyst>Contributor
link before the administration link, the Analyst>Contributor link is applied to the cube first.
However, if you run the same Analyst > Contributor Link again after the administration link, the
first Analyst > Contributor link is overwritten, and the second Analyst > Contributor link is run
after the administration link.
Analyst>Contributor links are activated automatically after every administration link if run using
the Analyst user interface rather than macros.
Running Import Data and Links more than Once
You can import data into specific cells only once before running Go to Production. If you run
import data to the same cells twice, the cells affected by earlier cube import blocks are overwritten.
You can run multiple administration links and Analyst > Contributor links before running Go to
Production. If you are targeting the production version of the application with an administration
link, you do not need to run Go to Production. A reconcile job is triggered by an activation process.
If the links target different cells, separate cube import blocks are created. If the links target the same
cells, the link-affected cells from the first link are overwritten.
Making Changes to the Development Application After a Link or Import Data Process
Some changes to a development application may affect a link or import data in the following ways:
● If the cubes that you are importing data into changed, you may have to re-create the source
files and go through the complete import data process, or re-create and re-execute links. If
changes were made that do not affect the cube that you are importing data into, you need only
to rerun Prepare Import.
● Any changes made to access tables, saved selections, or the e.List that result in a different pattern
of No Data cells for contribution e.List items that are common to both the development and
production applications result in the import queue being deleted.
● Creating access tables after Prepare Import has run causes the import queue to be deleted.
● If the items are mapped manually, the link must be updated or recreated after any changes to
dimension items.
Create an Administration Link
Chapter 9: Managing Data
Create an administration link to copy data between cubes in Contributor applications, or to import
data from IBM Cognos 8 data sources. If you are importing data from IBM Cognos 8 data sources,
Administration Guide 149

Chapter 9: Managing Data
150 Contributor
you must first create and publish an IBM Cognos package containing the data you want to import.
For more information, see "Importing Data from IBM Cognos 8 Data Sources" (p. 164).
Administration links will not run unless one or more job servers are monitoring the Planning content
store. For information about adding the Planning content store to a job server, see "Add Applications
and Other Objects to a Job Server Cluster" (p. 57).
Note: Any changes to the source file are not reflected in the target unless the administration link is
rerun.
Steps to Create Links Between Cubes
1. Click Administration Links, Manage Links.
2. Under the Administration Links pane, choose whether to add a link or edit an existing one:
● To add a link, click New.
● To edit a link, click Edit.
If the link definition specifies an application that no longer exists, the Select Link Source/Target
dialog box appears. Select a different source application, target application, or both, and then
click OK.
If you chose an application with an incompatible model structure, a message appears indicating
that the selected application is invalid and that the editor is empty. Close the editor, click Edit,
and then select a different application. Type a brief description of the source and target of the
link element.
3. Enter or edit the name and description of the link.
Both can have up to 250 characters. Link names must be unique and must not be empty or
consist only of spaces.
4. Choose Contributor Application as the data source type.
5. To tune administration link performance, click the Advanced button to adjust the amount of
e.List items that load in a single batch for both the source and target.
Note: this is not needed if selecting an IBM Cognos Package.
For more information on tuning batch sizes, see "Tuning Administration Links" (p. 158).
6. To use the standard configuration, click OK.
The Administration Link-Element dialog box appears.
7. Select the source application and cube.
The source application must be a production application. You can preview the dimensions of
a cube in the right pane.
8. Select the target application and a target cube.
The application can be either the production or development application.

9. Click Map to map source dimensions to a target dimension manually (p. 154), or click Map All
to map dimensions with the same name. You need at least one set of matching dimensions in
order to use the Map All feature.
The mapped dimension pairs now appear in the lower set of Map source to target dimensions
lists. A single line connects paired dimensions.
Tips:
● Double-click the connecting line (or either dimension) to confirm that the items in the
dimensions are mapped correctly.
● To edit the properties of a mapped dimension, click the source, target, or line between the
source and target dimension names and click edit.
● To remove a map, click the map and click Clear. Clear all created maps by clicking Clear
All.
10. In the Additional Options window of the Administration Link-Element dialog box, you can
choose to include annotations or attached documents. Do one of the following:
● To only include annotations, click Include Annotations.
● To only include attached documents, click Include Attached Documents.
11. Click Finish when you are done configuring the link element.
12. If you want to add a new element, click Yes. To return to the main Administration Links win-
dow, click No.
Note: If you add a new element, it must match the source used in the original link.
Both actions save the current element. You can change the order in which the elements are run
using the arrow buttons. For more information, see "Order of Link Elements" (p. 148).
13. If you want to execute the link, click Execute.
If you want to monitor the progress of an administration link, under Administration links, click
Monitor Links. For more information, see "Jobs" (p. 49).
Tip: If you receive an error message stating that the batch sizes are too large to load data, you
need to adjust the batch sizes. For more information, see "Tuning Administration Links" (p. 158).
To automate this process, see "Execute Administration Link" (p. 219).
Note: Applications defined in a link may no longer be available since the administrator last
created or modified the link. An application becomes invalid when the application ID is changed
because the application was transferred from a development environment to a production
environment.
Steps to Create Links with IBM Cognos Package as the Source
1. Click Administration Links, Manage Links.
2. Under the Administration Links pane, choose whether to add a link or edit an existing one:
● To add a link with IBM Cognos Package as the source, click New.
Chapter 9: Managing Data
Administration Guide 151

Chapter 9: Managing Data
152 Contributor
● To edit a link, click Edit.
If the link definition specifies an application or package that no longer exists, the Select Link
Source/Target dialog box appears. Select a different source package, target application, or both,
and then click OK.
If you chose a package with an incompatible model structure, a message appears indicating
that the selected package is invalid and that the editor is empty. Close the editor, click Edit,
and then select a different application. Type a brief description of the source and target of the
link element.
3. In the Administration Link Properties dialog box, enter or edit the name and description of the
link.
Both can have up to 250 characters. Link names must be unique and must not be empty, or
consist only of spaces.
Select IBM Cognos Package as the Data Source Type.
By default, the administration link will run a prepare import job to process import data ready
for reconciliation. Click the Advanced button and clear the Run Prepare Import Job check box
to change the default setting.
4. In the Select an IBM Cognos Package as the Link Source dialog box, browse for an IBM Cognos
Package in IBM Cognos Connection by clicking the ellipses button.
If you select a package not published from Framework Manager you will get an error message
stating that the package you have selected cannot be used as a source for an administration
link because it was not published from Framework Manager.
5. Click a query subject.
6. Select the available query items in the query subject and move them to the Selected Query Items
pane.
Select the Display preview of selected query item check box to preview the query items. The
preview option only works with query items that have not been selected, and helps you select
the correct query items.
7. Click OK to bring the query items into the link.
8. In the Administration Link-Element dialog box, select the target application and a target cube.
The application has to be Development.
9. Click Map to map source dimensions to a target dimension manually (p. 154), or click Map All
to map dimensions with the same name. You need at least one set of matching dimensions in
order to use the Map All feature.
The mapped dimension pairs now appear in the lower set of Map source to target dimensions
lists. A single line connects paired dimensions.
Tips:
● Double-click the connecting line (or either dimension) to confirm that the items in the
dimensions are mapped correctly.

● To edit the properties of a mapped dimension, click the source, target, or line between the
source and target dimension names, and click edit.
● To remove a map, click the map and click Clear. Clear all created maps by clicking Clear
All.
10. If you want to select the columns containing the data, click Mark Data.
There are two main principles on how to structure these links:
● Anything which is a measure in the FM model must be marked as data before it can be
paired with a dimension.
● Anything marked as data must be paired with a dimension and must not be left unpaired
in the link.
Note: Mark Data is not available once you have mapped your data.
11. In the Administration Link - Element dialog box, click Next to pick unmapped source Query
Items and unmapped target dimension items.
12. In the Additional Options window of the Administration Link-Element dialog box, you can
choose to include annotations or attached documents. Do one of the following:
● To include only Annotations, click Include Annotations.
● To include only Attached Documents, click Include Attached Documents.
13. Click Finish when you are done configuring the link element.
14. If you want to add a new element, click Yes. To return to the main Administration Links win-
dow, click No.
Note: If you add a new element, it must match the source used in the original link.
Both actions save the current element. You can change the order in which the elements are run
using the arrow buttons. For more information, see "Order of Link Elements" (p. 148).
15. If you want to execute the link, click Execute.
If you want to monitor the progress of an administration link, under Administration links, click
Monitor Links. For more information, see "Jobs" (p. 49).
To automate this process, see "Execute Administration Link" (p. 219).
Note: Applications defined in a link may no longer be available since the administrator last
created or modified the link. An application becomes invalid when the following occurs:
● The application ID is changed because the application was transferred from a development
environment to a production environment.
● When changing the package or target application, you chose a package with an incompatible
model structure.
Chapter 9: Managing Data
Administration Guide 153

Chapter 9: Managing Data
Map Dimensions Manually
154 Contributor
Manually mapping dimensions may bring performance improvements for some links. A manually
mapped link filters the data at the source, so less data is moved. Auto-mapped links do not perform
such filtering, so it is possible that more data is moved than if the same link used manual mapping.
Steps
1. Click Map.
The Map Items dialog box appears. Any matching dimension items are highlighted.
If a source dimension does not map to any target dimension, it can be treated as an extra source
dimension. If the items in the source and target dimensions do not match, either a manual map
or loading of an allocation table is required. For example, if the source item is Jan-03 and the
target item is 1-03, a manual map is required. Or you can load an allocation table from Analyst
that you have already created to map those source and target items that don’t match.
If items in a source or target of the manually mapped link are added, the link must be manually
updated to account for the new items in order to correctly run the load.
If you load an allocation table, you can synchronize to ensure the source allocation table in
Analyst matches the allocation table in Contributor.
2. If you want to map items based on capitalization, select Case Sensitive.
3. If you want to include calculated items (shown in bold) select Calculated items.
4. If matching dimensions are highlighted, click OK to accept them.
The Map Items dialog box closes and returns you to the Map Source to Target dialog box.
5. If some unmatched items remain in the Map Items dialog box, click Manually Map.
If you select Manually Map, then select a source dimension and target dimension, click Add,
and click OK.
Note: It is okay to have unmapped items.
The matching pairs of dimensions move under the unmapped dimension fields to the mapped
dimension fields and a line connects the two dimensions.
If you have a long list of dimension items to map, you can filter them based on the first characters
in the item name.
Note: This filter applies only to items that appear in the Dimension Items list. It does not affect
what is loaded into the target.
6. In the Filter box, type the character you want to filter with.
Only the items that begin with that character appear.
Tip: To remove the filter, delete the character in the Filter box .
7. In the Map Items dialog box, click Substring.
The Select Substring dialog box appears with the longest item name in the dimension list.

When you use a substring, all the items that match the substring are rolled up into one item.
For example, if you have dimension items named Budget 1, Budget 2, and Budget 3 and you
applied the substring BUD, all three items are rolled into one dimension item to be loaded into
the target dimension.
Note: Unlike filtering by characters, using a substring applies to what is included in the load
as well as what is viewed in the Dimension Items list. You can use a substring when mapping
dimensions manually or automatically.
8. Click in the Substring box to place bars at the beginning and end of the substring. If the substring
appears in the front of the string, place a single bar at the end of the substring.
To remove the bar, right-click it.
9. Click OK. The dimension items are now filtered by the number of characters you selected.
Use an Allocation Table in Administration Links
If you have two lists in Contributor that do not have an exact character match during mapping,
you can load an allocation table from Analyst into an administration link. You can map between
two e.Lists, an e.List to a D-List, a D-List to an e.List, and a D-List to a D-List. The allocation table
allows you to map items from one list to another list that do not match up, allowing you the ability
to reuse a mapping.
While a manual mapping can be set up in an administration link, it cannot be reused. With an
allocation table, you can set up a mapping in Analyst and reuse this not only in Analyst but also
in administration links. Once you load the allocation table into the administration link, you can
ensure that the data remains up to date by using the Synchronize functionality in Administration
Links, Manage Links. If the underlying allocation table in Analyst has changed, synchronizing
updates it in Contributor.
Steps
1. Create a new administration link, select Contributor Application as Data Source Type.
2. Select the source and target dimensions (e.List to e.List, e.List to D-List, D-List to e.List, or D-
List to D-List).
3. Click Map.
The Map Items dialog box appears. Any matching dimension items are highlighted.
4. To load an allocation table, click Allocation Table.
5. In the Select A-Table dialog box, select the library that contains the A-Table and then select
the A-Table that you want to use. You will see a preview of the A-Table in the Preview field.
6. Click OK.
7. The A-Table you selected is loaded into the Map Items dialog. Create mappings for any other
dimensions in the source and target applications, then click Finish.
Chapter 9: Managing Data
Administration Guide 155

Chapter 9: Managing Data
Validate Administration Links
If you have an administration link based on an Analyst A-Table, if a synchronize with Analyst has
been done, or if there have been any changes to the A-Table in Analyst, you should validate the
link.
Steps
1. In the Administration Console, expand the Administration Link tree and click Manage Links.
2. In the Select for Validation or Synchronization column, select the check box for each of the
links that you want to validate.
3. Click Validate.
4. You can monitor the progress of the validation by clicking Monitor Links in the tree under
Administration Links. After the validation job runs, if the link or links are valid the edit status
will be COMPLETE. If it the link or links are invalid, the edit status will be UNKNOWN.
Check the administration link to ensure that the source and target cubes are available, and all
dimensions are mapped.
Note: You can automatically validate one or more administration links by using the Validate
Administration Links macro.
Synchronize Administration Links
156 Contributor
When you create an administration link based on an Analyst A-Table, there is always the possibility
that the underlying A-Table in Analyst can change over time. You can synchronize to ensure the
A-Table you have used in an administration link is up to date.
Steps
1. From the Contributor Administration Console, under Administration Links, click Manage
Links.
2. In the Select for Validation and Synchronization column, select the check box for each admin-
istration link that you want to synchronize.
3. Click Synchronize.
4. You can monitor the progress of the synchronization by clicking Monitor Links in the tree
under Administration Links. After the synchronization job runs, the edit status will be COM-
PLETE.
Note: You can automatically synchronize one or more administration links by using the Syn-
chronize Administration Links macro.

View Items in a Dimension
You can preview the items that appear in a dimension.
Steps
Remove a Dimension
1. Select either a source or target dimension.
2. Click the preview button .
You can remove a selected dimension.
Steps
1. In the Map Source to Target dialog box, click the source dimension you want to remove.
2. Click the remove button .
This removes the description designation from a row or column. The row or column is now
treated as values.
Running Administration Links
Administration links are run using the job system and are scalable. They can be automated using
macros, see "Administrator Links (Macro Steps)" (p. 219).
When a link targets the development application, you must run Go to Production so that users can
access the linked data. The data is moved into the prepared import blocks. You can see the results
of this in the Import Data, Prepared Data Blocks tab (p. 176).
When a link targets the Production application, there is no need to run Go to Production. An
administration link job is created when the link is executed. At the job end, an activate process is
called. This moves the data into the import production queue and creates a snapshot of the data at
the time the link was executed. Then a reconcile job is triggered, which updates the e.List items
with the new data.
Exporting and Importing Administration Links
You can export administration links from one application and import it into another using the
Administration Console or the Deployment Wizard (p. 170). To import administration links using
the Administration Console, the source and target applications must still exist, and the metadata
must be unchanged. In addition, the application IDs must remain the same.
The process is as follows.
❑ Export the administration links from the Contributor applications. You can only export one
link at a time.
❑ Backup and remove the Contributor applications from the current Planning Content Store and
add them to the new Planning Content Store.
Chapter 9: Managing Data
Administration Guide 157

Chapter 9: Managing Data
❑ Import the administration links into the new Planning Content Store.
Steps
1. Click Administration Links, and Manage Links.
2. Click the administration link and then click Export.
3. Enter the name and location, and click Save. The administration link is saved with a .cal
extension.
4. To import an administration link, click the Import button, and select the administration link
file.
Tuning Administration Links
If it is given an edit status of UNKNOWN, check the administration link to ensure that the
source and target cubes are available, and all dimensions are mapped.
Note: When importing an administration link created using IBM Cognos Planning version 7.3
SP3 or earlier, the source and target batch size setting is 1, which loads one target/source e.List
item into batch. This was the default behavior of the previous versions of IBM Cognos Planning.
For more information, see "Tuning Administration Links" (p. 158).
Administration link performance can vary for a number of reasons, such as the e.List length of both
the target and source, the size of the target and source, and the complexity of the link. Link perform-
ance may be slower on certain configurations, even when large data volumes are not present. For
more information, see "Variables That Affect Performance of Administration Links" (p. 159).
If necessary, you can tune administration links to get the best performance. e.List items are loaded
into memory in batches. By adjusting the batch sizes for both the source and target e.List items that
are loaded to process the administration link, you may improve performance. This is particularly
true when there is a link with a many-to-many relationship (p. 159), because these typically need a
lot of processing power.
Note: You cannot tune administration links that use IBM Cognos Packages as their source. This is
because IBM Cognos Packages do not load from e.List items.
A batch is a set of data that is to be transferred can include data from more than one e.List item.
A batch can also target multiple e.List items.
Important: When changes occur to a model you should evaluate whether you need to retune the
administration link.
When Should You Tune an Administration Link?
158 Contributor
Many administration links do not require tuning adjustments. This is because the default settings
work well for many administration link scenarios. To see if your administration link needs tuning,
we recommend that you create and run the administration link using the default settings, and then
adjust the batch size limits if performance becomes an issue. For more information, see "Determine
Optimal Batch Size" (p. 160).
Tuning administration links affects only the time taken to move data, not the time taken to incor-
porate the data into the target application via a reconcile job. Links that target the development

application spend all their time moving data through the inter_app_links job. These links do not
trigger reconcile jobs, so if they are taking a long time, you should consider tuning them.
Links targeting the production application spend time in two actions:
● moving data via an inter_app_links job
● incorporating that data into the target application via a reconcile job
To determine whether or not tuning the administration link will be beneficial, review the amount
of time it takes to move data versus any time spent on the reconciliation.
You can see the inter_app_links job in the Monitor Links window, and the reconcile job in the Job
Management window of the target application.
Tip: If you are running multiple administration links that target the same application, consider
targeting the development application and running Go to Production. This means that reconciliation
is run once instead of multiple times. Alternatively, instead of having multiple links, you can have
multiple link elements from different applications in the same link targeting the production applic-
ation. In this case, reconciliation is run only once.
Variables That Affect Performance of Administration Links
Many factors play a role in determining optimal performance for running administration links.
Types of Link
Where the source and target applications share the same e.List, and each source e.List item is mapped
to its matching target e.List item, the link has a one-to-one relationship. The amount of effort to
run this link is determined by the number of mappings between e.List items.
Links that have a single source e.List item targeting multiple e.List items have a one-to-many rela-
tionship. The effort required to run this link is determined by the number of target e.List items.
Links where many source e.List items target a single e.List item have a many-to-one relationship.
The effort required to run this kind of link is determined by the number of source e.List items.
Links where multiple source e.List items are mapped to multiple e.List items have a many-to-many
relationship. These links typically need a lot of processing power, because the effort needed to run
them is calculated by the number of source e.List items multiplied by the number of target e.List
items. You may get the most benefit from tuning these links.
Number of Processors
The number of processors and the amount of available RAM directly affect performance.
If any of your servers in the job server cluster have more than 4 CPUs available, we recommend
that you increase the Job Item Count multiplier per machine setting in the epInterAppLinkResources.
xml file (\cognos\c8\bin). The default setting is 4 CPUs per job server. However,
having fewer than 4 CPUs does not negatively affect performance.
The file is installed as read-only. We recommend that you back up the file and reset the read-only
flag to write in order to change the CPU number. You must make the same change to the file on
all servers in the cluster.
Note: This setting only affects the administration link performance.
Chapter 9: Managing Data
Administration Guide 159

Chapter 9: Managing Data
Model Changes
Changes to the model affect how the administration link performs. If you tune an administration
link and it shows improved performance and then a change occurs in the model, the optimization
may become invalid. This is because the change can affect the overall shape of the administration
link (e.List length, cube size, and so on) that the tuning was based on.
Determine Optimal Batch Size
Adjust the number of source and target e.List items processed at one time to optimize performance
of the administration link.
Steps
1. While the administration link runs, monitor the memory utilization on the least powerful server
in the job server cluster on which administration links run.
2. Adjust the batch size for both the source and target and rerun the administration link. We
suggest that you increase the source batch size where possible before increasing the target batch
size.
Set Source Batch Size
160 Contributor
● For the source, if there are 150 source e.List items, try entering 75. If that does not work,
try 50 and so on.
● For the target, divide the number of e.List items by the number of physical processors
multiplied by 2.
For example: 2250 e.List items/(14 processors*2)
This gives you a figure of 80.
If this is too large, try multiplying the number of processors by 4 and so on.
The values for Limit To must be positive whole numbers and greater than zero in order for the
tuning settings to be valid.
3. Monitor the memory utilization on the same server to see if it has improved.
4. If not, adjust the numbers and run the administration link again.
You can set the amount of source e.List items that are processed at one time. By default, all
applicable e.List items are processed into the relevant target(s). The default setting is No Limit for
newly created administration links, which loads all the source e.List items in one batch. This means
that each e.List item is read once and then grouped and loaded into the targets. This setting may
work well, but if you have a large model, you may need to reduce the setting.
Note: When importing an administration link created using IBM Cognos Planning version 7.3 SP3
or earlier, the source and target batch size setting is 1, which loads only one source e.List item at
a time. This was the behavior of the previous versions of IBM Cognos Planning.
Steps
1. In the Create New Link dialog box, click Advanced.

Set Target Batch Size
2. If you want to load all e.List items at once, ensure that No Limit is selected.
3. If you want to divide your loads into batches, type a number into the Limit To box.
Note: The values for the Limit To box must be positive whole numbers and greater than zero
in order for the tuning settings to be valid.
4. If the performance is acceptable, leave the Source Batch Size as no limit. If you get errors, reduce
the size.
You can set the number of target e.List items that are processed in one batch. The default setting
is 1 for newly created administration links, which loads the source batch into one e.List item at a
time.
Steps
1. In the Create New Link dialog box, click Advanced.
2. If you want to target all e.List items at once, select No Limit.
3. If you want to divide your loads into batches, enter a number into the Limit to box.
4. Click OK.
You now need to configure the link element (p. 149).
Tuning Existing Administration Links
Administration links created using IBM Cognos Planning version 7.3 SP3 or earlier can be imported
(p. 157) and reused. These administration links processed each source and target item one at a time.
Now, source and target items are processed in batches and those items are held in memory, reducing
the number of transfers that occur.
When a previously created administration link is imported, the source and target batch size is set
to 1, which loads one source and target item into a batch for processing. We recommend that you
change the source batch size to No Limit, which is the default value for any newly created adminis-
tration link. By adjusting this setting you should see performance gains. You can then try to adjust
the batch size settings to further improve performance.
Troubleshooting Tuning Settings
An administration link will fail if the source and/or target batch sizes are too large because too
much data will be loaded into memory. If you receive the following error message, set the source
and target batch sizes to a smaller number and rerun the administration link.
Failed to load source data.
You could try setting the source batch size to less than
X so that fewer source e.List items are loaded at the same time.
You could try reducing the target batch size to less
than X so that fewer target e.List items are processed at the same
time.
(where X is the recommended batch size)
Chapter 9: Managing Data
Administration Guide 161

Chapter 9: Managing Data
Troubleshooting Remote Call Time-Out
System Links
162 Contributor
When you build or modify links in the Contributor Administration Console, queries are executed
to get metadata into the Contributor Administration Console for display. On particularly large
queries, you may receive a message similar to the following:
502 - Bad Gateway URL: http://localhost:80/cognos8/cgi-bin/cognos.cgi,
SOAP action: http://developer.cognos.com/schemas/
planningAdministrationConsoleService/1~~HTTP/1.1
502 Bad Gateway~~Content-Length: 252~~Content-Type: text/html~~Server: Microsoft-
IIS/6.0~~~~~~
We recommend that you increase the Remote Call Time-out in Seconds setting to 7200 seconds in
the epAdminLinksResources.xml file, located at \cognos\c8\bin. The file is installed
as read-only. We recommend that you back up the file and reset the read-only flag to writable.
After changing this setting, the Planning service needs to be stopped and restarted on the machine
that is building or modifying the link.
Administrators can set up links that are run from a Web client session so that Web client users can
move data from a cube in a source application to a cube in a target application. A system link is a
pull link, rather than a push link.
A system link can target hidden, read-only, and writable cells.
System links move date from one source cube in one application to one target cube in another
application. System links are stored with the application, whereas administration links are stored
in a separate datastore. The target for system links must be in the production version of the
application, whereas the target for administration links can be in the production or development
version of the application.
You cannot map an e.List dimension to an ordinary dimension in a system link, unlike in an
administration link. This is for performance reasons. If many e.List items must be loaded for a link,
this potentially takes a lot of resources. An administration link can run across job servers and is
scalable, so resources are usually not a problem. But a system link runs on the Web client computer
and is not scalable. If you must map an e.List dimension to an ordinary dimension, use an adminis-
tration link. A target e.List item can have only one source e.List item mapped to it, but one source
e.List item can be mapped to many e.List items.
To create a link, administrators must be granted the access rights System link as source, and System
link as target, for the relevant applications. In addition, the Admin Options setting Act as system
link source must be set to Yes for source applications. For more information, see "Admin
Options" (p. 79). Otherwise, you can still create links using this source, but the Web user cannot
run the link. You assign the link to an e.List item in the target application.
To run the link, the user must have write access to the e.List item that the link is assigned to. They
do not require rights to the source cube. Links are executed on the client computer through Get
Data. They can be run only from the target application. Client users cannot edit system links.
Note: For Classic Contributor Web Client users, the Get Data extension must be configured before
you can run a system link or local link. For more information about configuring the Get Data
extensions, see "Configure Classic Client Extensions" (p. 301).

The Go to Production process does not have to be run after you set up a system link.
The history of system link actions is stored as an annotation for cubes and targeted e.List items, if
enabled. When a system link is run, a new annotation is created for that link in the open e.List item.
If the link is executed again by the same user or another user, the same annotation is updated. In
addition, a separate history dialog shows all history related to the links that apply to the open e.List
items.
Create a System Link
Applications defined in a link may no longer be available since the administrator last created or
modified the link. An application becomes invalid when the following occurs:
● The application ID is changed because the application was transferred from a development
environment to a production environment.
● When changing the source or target application, you chose an application with an incompatible
model structure.
To use an application as a source for a System Link, you must first set Act as system link source in
Admin Options to Yes. For more information, see "Admin Options" (p. 79).
Steps
1. Click Production, System links.
2. Choose whether to add a system link or edit an existing one:
● To add a link, click New.
● To edit a link, click Edit.
3. If the link definition specifies an application that no longer exists, the Select Link Source/Target
dialog box appears. If this happens, select a different source application, target application, or
both, and then click OK.
If you chose an application with an incompatible model structure, a message appears indicating
that the selected application is invalid and that the editor is empty. Close the editor, click Edit,
and then select a different application.
4. Type a descriptive name for the system link.
5. Select a Source Application, and a Source Cube.
The source application must be a production application, which means it contains an e.List
and Go to Production was run.
6. Select a Target Cube.
7. Map the source dimensions to the target dimensions manually (p. 154), or click Map All to map
dimensions with the same name.
You must have at least one set of matching dimensions to use Map All.
Chapter 9: Managing Data
Administration Guide 163

Chapter 9: Managing Data
The mapped dimension pairs move to the fields below, and a line connects the two. This line
signifies that these dimensions are a matched pair.
Note: The Substring option is unavailable to system links on the e.List dimensions because you
cannot have multiple sources or multiple targets due to the potentially large number of nodes
that would need to be downloaded to the client in order to execute the system link.
8. In the Additional Options window of the Administration Link-Element dialog box, you can
choose to include annotations or attached documents. Do one of the following:
● To include only Annotations, click Include Annotations.
● To include only Attached Documents, click Include Attached Documents.
9. In the System Link dialog box, click Finish.
Importing Data from IBM Cognos 8 Data Sources
164 Contributor
You can import data into IBM Cognos 8 Planning - Analyst and IBM Cognos 8 Planning - Contrib-
utor from any data source that can be published as an IBM Cognos 8 package.
For more information about supported data sources, visit the IBM Cognos Resource Center (http:
//www.ibm.com/software/data/support/cognos_crc.html).
There are additional considerations when importing SAP BW data into IBM Cognos 8 Planning.
For more information, see "Working with SAP BW Data" (p. 167).
For information on IBM Cognos 8 Planning configuration requirements for SAP BW, see the IBM
Cognos 8 Planning - Installation and Configuration Guide.
You must have Framework Manager installed. If you are working with SAP BW data, you must
install the SAP gateway functions. For more information, see the IBM Cognos 8 Planning - Install-
ation and Configuration Guide.
Importing data from IBM Cognos 8 data sources involves the following tasks.
❑ In IBM Cognos Connection, create a data source connection, see the IBM Cognos 8 Adminis-
tration and Security Guide for more information.
❑ In Framework Manager, create a new project and import the metadata into the project (p. 165).
❑ In Framework Manager, model the source. See the Framework Manager User Guide for more
information.
❑ Create and publish the IBM Cognos package to IBM Cognos Connection (p. 166).
❑ If importing into a Contributor application, in the Contributor Administration Console, create
and run an administration link.
Tip: You can create and schedule macros that run administration links.
❑ If importing into an Analyst model, choose one of the following options:
● Select an IBM Cognos package as a source in a D-List Import.
● Select an IBM Cognos package as a source in a D-Link.

● Select an IBM Cognos package as a source in an A-Table, or import an IBM Cognos
package as a Source in an A-Table.
You can also automate the import of IBM Cognos packages using the @DListItemImportPackage
macro.
Create a Framework Manager Project and Import Metadata
A project is a set of models, packages, and related information for maintaining and sharing model
information.
Steps
1. From the Windows Start menu, click Programs, IBM Cognos 8, Framework Manager.
2. In the Framework Manager Welcome page, click Create a new project, and specify a name and
location.
You can add the new project to a source control repository, see the Framework Manager Help
for more information.
3. In the Select Language page, click the design language for the project.
You cannot change the language after you click OK, but you can add other languages.
Note: If an SAP BW server does not support the selected language, it uses the content locale
mapping in IBM Cognos Configuration. If a mapping is not defined, Framework Manager uses
the default language of the SAP BW server.
4. In the metadata source page, select Data Sources.
5. Select a data source connection and click Next.
If the data source connection you want is not listed, you must first create it, see the IBM Cognos
8 Administration and Security Guide.
6. Select the check boxes for the tables and query subjects you want to import.
Tip: For usability, create a package that exposes only what is required.
7. Specify how the import should handle duplicate object names.
Choose either to import and create a unique name, or not to import. If you choose to create a
unique name, the imported object appears with a number. For example, you see QuerySubject
and QuerySubject1 in your project.
8. If you want to import system objects, select the Show System Objects check box, and then select
the system objects that you want to import.
9. Specify the criteria to use to create relationships and click Import.
For more information, see the Framework Manager User Guide.
10. Click Next and then Finish.
Chapter 9: Managing Data
Administration Guide 165

Chapter 9: Managing Data
Note: You save the project file (.cpf) and all related XML files in a single folder. When you
save a project with a different name or format, ensure that you save the project in a separate
folder.
Create and Publish the IBM Cognos Package
166 Contributor
You create and publish a package to make the data available to IBM Cognos 8 Planning.
Steps to Create a Package
1. Click the Packages folder, and from the Actions menu, click Create, Package.
2. In the Provide Name page, type the name for the package and, if you want, a description and
screen tip, and click Next.
3. Specify whether you are including objects from existing packages or from the project and then
specify which objects you want to include.
4. Choose whether to use the default access permissions for the package:
● To accept the default access permissions, click Finish.
● To set the access permissions, click Next, specify who has access to the package, and click
Next.
You can add users, groups, or roles. See the Framework Manager User Guide for more
information.
5. Move the language to be included in the package to the Selected Languages box, and click
Next.
6. Move the sets of data source functions you want available in the package to the Selected function
sets box.
If the function set for your data source vendor is not available, make sure that it was added to
the project.
7. Click Finish and choose whether to publish the package.
Steps to Publish a Package
1. Select the package you want to publish.
2. From the Actions menu, click Package, Publish Packages.
3. Choose where to publish the package:
● To publish the package to the report server, click IBM Cognos 8 Content Store. Click
Public Folders to publish the package to the public folder. You can create folders in the
public folder also. Click My Folders to create your own folder and publish the package to
it.
● To publish the package to a network location, click Location on the network.

4. To enable model versioning when publishing to the IBM Cognos 8 Content Store, select the
Enable model versioning check box and type the number of model versions of the package to
retain.
Tip: To delete all but the most recently published version on the server, select the Delete all
previous model versions check box.
5. If you want to externalize query subjects, select the Generate the files for externalized query
subjects check box.
6. By default, the package is verified for errors before it is published. If you do not want to verify
your model prior to publishing, clear the Verify the package before publishing check box.
7. Click Publish.
If you chose to externalize query subjects, Framework Manager lists which files were created.
8. Click Finish.
Working with SAP BW Data
The SAP BW model is an OLAP source and is optimized for reporting rather than for high volume
access that is sometimes required for planning activities. To efficiently access data for IBM Cognos 8
Planning, create a detailed fact query subject that will access fact data at a detail level suitable for
use with IBM Cognos 8 Planning.
Tip: If you have OpenHub, you can use it to generate a text file or database table from SAP BW.
You can then manually create a Framework Manager model and IBM Cognos Package from the
tables and then import the package into Planning using an Administration Link, D-Link, or D-List
import.
For IBM Cognos products to be able to access SAP BW as a data source, the user accounts used to
connect to SAP must have specific permissions. These permissions are required for the OLAP
interface to SAP BW and are therefore relevant to both reporting and planning activities.
For more information about guidelines for working with SAP BW data, see the Framework Manager
User Guide.
For more information about access permissions for modelling and reporting access, see the IBM
Cognos 8 Planning Installation and Configuration Guide.
For information about setting up your environment to work with SAP BW and Planning, see the
IBM Cognos 8 Planning Installation and Configuration Guide.
Create a Detailed Fact Query Subject
Chapter 9: Managing Data
The detailed fact query subject is a model query subject based on database query subjects and cal-
culations. The relational folder is where the SAP star schema is imported to. The detailed fact query
subject is the logical representation of the fact table and the query subjects in the relational folder
Administration Guide 167

Chapter 9: Managing Data
are the physical representation of the SAP fact table. We recommend that you do not modify the
contents of the relational folder, unless advised by customer support.
Steps
1. In Framework Manager, click the Key Figures dimension.
2. From the Tools menu, click Create Detailed Fact Query Subject.
3. In the metadata wizard, select the data source you want to use.
You can create a new data source by clicking the New button and specifying SAP BW for
Planning as the type.
4. Click OK.
Framework Manager creates a model query subject named Detailed_Key_Figures and a separate
folder containing references to the relational objects. The references to the relational objects
are the physical layer.
5. Create the package.
Note: Packages that contain the Detailed_Key_Figures query subject are only accessible or
supported for the report authoring tools, such as Query Studio and Report Studio if they are
hidden by doing the following:
● In the Define Objects screen click the down arrow and choose Hide Component and Chil-
dren.
● Click Detailed_Key_Figures and Relational_Objects.
6. Publish the package.
Recommendation - Query Items
It is a common requirement to concatenate two or more fields from a data source when creating
D-Lists in Analyst. When importing D-Lists from an IBM Cognos Package, you perform the con-
catenation in Framework Manager by creating a new query item. The query item can then be
included in the published package and imported into D-Lists and used in D-Links.
When working with SAP BW, you can use a concatenated query item to build a D-List in Analyst.
However, when you create a link, either in Analyst or Contributor, then the concatenated query
item cannot be used. Instead, use one of the underlying query items for the source and use a substring
on the target dimension.
When applying a filter in Framework Manager, you specify how it is used by selecting a usage
value. To see the filtered data when publishing a package in Planning, select Always or Optional.
See the Framework Manager User Guide for more information.
Recommendation - Hierarchy
168 Contributor
These recommendations will help improve performance when working with the SAP BW import
process.

● Use manageably sized dimensions when importing SAP BW data. This is because Planning relies
on lookups against the SAP BW hierarchies during the import process, so larger hierarchies
slow down the import process. This may require modelling in SAP BW since it is at a higher
level of detail than the Planning process requires.
● Where possible, take data from the lowest level in the BW hierarchies. This is because data is
taken from the fact table level and aggregated to the level selected in the Planning link. The
further up the hierarchy that members are mapped into Planning, the more aggregations are
needed to be recreated during the import process. This may require modelling in SAP BW since
it is at a higher level of detail than the Planning process requires.
Recommendation - Hiding the Dimension Key Field
When working with SAP BW data, the Dimension Key field for any dimension should be hidden
in the Model (not the package) - both for the OLAP and Detailed Fact Query Subject access before
the package is published. It is not intended for direct use from within IBM Cognos Planning.
Working with Packages
To avoid a high number of Query Subjects and Query Items when working with and creating
packages in Planning, you should make them as specific as possible so they contain only objects
that are useful to a Planning user.
Using a naming convention may also be useful, like using Planning as a prefix for your packages.
For advanced users, you could also create a single package that holds all of the source objects.
Troubleshooting Detailed Fact Query Subject Memory Usage
When executing administration links that use the Detailed Fact Query Subject, one of the internal
IBM Cognos components builds temporary files in the Temp folder under the IBM Cognos install-
ation directory. The temporary files are deleted after the query completes, but these files can be
large, depending on how much data is being retrieved. If the drive that contains the Temp folder
does not have enough space to contain the temporary files, the query will fail and you will receive
the following error:
Error Message: DM-DBM-0402 COGQF driver reported the following:~~~~COGQF failed to
execute query - check logon / credential path~~~~DM-DBM-0402 COGQF driver reported the
following:~~~~RQP-DEF-0177 An error occurred while performing operation '
sqlOpenResult' status='-28'.~~UDA-SQL-0114 The cursor
supplied to the operation "sqlOpenResult" is inactive.~~UDA-SOR-0005
Unable to write the file.~~~~~~DM-DBM-0402 COGQF driver reported the following:~~~~
Make at least 2 MB of hard drive space available on the installation location’s drive. If you still
receive the error, then make more hard drive space available.
Chapter 9: Managing Data
Administration Guide 169

Chapter 9: Managing Data
Deploying the Planning Environment and Viewing the Status
of Deployments
Export a Model
You can export or import complete models, macros, administration links, or Analyst libraries with
or without the associated data from IBM Cognos 8 Planning - Contributor or Analyst. You deploy
a model by exporting it from one environment and importing it into another.
You can export a model structure, with or without data, to move between development, test, and
production environments or to send a model with or without data to IBM Cognos Customer
Resource Center.
When you export a model, IBM Cognos 8 Reports, Events, or Framework Manager Models asso-
ciated with the Planning Network are not exported.
The model structure and data are exported to the deployment directory location set in IBM Cognos
Configuration.
You can backup an application by exporting it, but we do not recommend this as a substitute for
database backup.
We recommend that you sign in to all namespaces before beginning the export.
Steps
Import a Model
170 Contributor
1. From the Tools menu, click Deployment and then click one of the following:
● Export Model
● Export Model and Data
2. In the Welcome to the Export Deployment Wizard page, click Next.
3. Select the objects you want to export and click Next.
Selecting a top level object will select all the children of that object.
4. Type a new name for the export, or choose a name from existing deployments and click Finish.
5. Click OK.
The export request starts on the server.
You can view the progress of the export in the Monitoring Console on the Deployments tab.
To transfer the deployment to a new environment, move the export folder from the source
deployment directory location to the deployment directory location for the target environment.
Compress the export folder to transfer your export to IBM Cognos Resource Center.
You can import a model or object to move an application into a test or production environment.
Models for import must be in the deployment directory location set in IBM Cognos Configuration.

You can import macros, administration links, applications, Analyst libraries, and security rights
from the source Planning Content Store that were exported during a previous deployment. You
can select exported objects for import or import an entire model. If a model was exported with
data, then the data will be used during the import.
You can import administration links and macros even if they reference an application that is not
in the target destination. If imported with a related application, macros and administration links
are automatically mapped to the target application.
Through the import process, you can change the target datastore and security for your model. The
deployment wizard attempts to map security settings for users, groups, and roles. If you are using
different namespaces or changing user, group, or role mappings, you may have to complete some
of the mapping manually.
The security settings for the source are applied to the user, group, or role to which you map. You
can map source users, groups, and roles together or individually to any single target user, group,
or role. When mapping a number of users, groups, or roles, the target maintains the greatest level
of security privileges. Any unmapped items are mapped to Planning Rights Administrator and do
not appear individually as a user, group, or role in the target.
Application IDs and object names must be unique within the Planning Administration Domain.
During the import processes, if duplicate names or IDs are found, you are warned. If you proceed
with the import without changing names and IDs, then any existing applications or objects with
common names or IDs will be overwritten.
To import Contributor applications, you must have at least one configured datastore and the
Planning content store must be added to a job server. A datastore is not required to import Analyst
libraries, macros, or administration links.
Steps
1. From the Tools menu, click Deployment and then click Import.
2. In the Welcome to the Import Deployment Wizard page, click Next.
3. In the Deployment Archive Name page, select a deployment to import and click Next.
4. In the Import Object Selection page, select the objects for import and click Next.
Selecting a top level object selects all the children of that object.
5. In the Namespace Mapping page, select the target namespace for each source namespace, and
click Next.
6. The User Group Role Mapping page contains a tab for each namespace mapping. For each
mapping, assign the correct target user, group, or role to each source by clicking the ellipsis
(…) button.
7. On the Select entries (Navigate) page, in the available entries directory, click the namespace
that contains the target user, group, or role.
8. From the selected entries, select the target user, group, or role and click OK.
Chapter 9: Managing Data
Administration Guide 171

Chapter 9: Managing Data
9. Complete the user, group, or role mapping for each Namespace mapping. Once you have
completed mapping each source user, group, or role to the target, click Next.
10. For each application or library with a warning next to it in the Object Mapping page, click the
ellipsis (…) button to change the configuration settings. You can also map all target options
by clicking Map All and adding a prefix or suffix to the object names. You can also set the job
server cluster for the application.
11. On the Configuration settings page, type new names, IDs and locations of files, and click OK.
For an Oracle or DB2 datastore, you must identify tablespaces for data, indexes, blobs, and a
temporary tablespace.
12. To avoid overwriting macros or administration links, for each object with a warning next to
it in the Object Mapping page, type a new name for the target object directly into the target
column.
13. Optionally, if you are importing a model without data, select the option to automatically go
to production with all imported applications during the import process.
14. If you are overwriting objects, you will be prompted to confirm the import, to continue, click
Yes.
15. Click Finish.
16. Click OK.
The import request starts on the server.
You can view the progress of the export in the Monitoring Console on the Deployments tab.
If you did not set the job server cluster in the Map All dialog, refresh the console after the transfer
is complete and add any newly created applications to a job server cluster.
For more information, see "Add Applications and Other Objects to a Job Server Cluster" (p. 57).
Tip: During the import process, some application options are excluded from the transfer because
they do not apply to the new application location, for example, display names, backup location,
and publish options are excluded. If these options are required, you can include them by modifying
the AdminOptions to exclude during Limited transfer or AdminOptions to exclude
during Full transfer resource values in the \bin\epPNHelperResource.xml
file.
View the Status of Existing Deployments
172 Contributor
If the export or import deployment request fails, you can view the errors. You can also view the
status of export and import processes currently running on the server through the Monitoring
Console.
Steps
1. From the Tools menu, click Deployment and then click View Status of Previous Exports and
Imports.

2. In the Welcome to the View Existing Deployment Wizard page, click Next.
3. Select the request and click Next.
The log of the deployment request appears. Errors and warnings are shown for failed requests.
Troubleshooting Out of Memory Exception When Exporting During a Deployment
You may receive an "Out of Memory" message when doing an export during a deployment.
On all machines that are running the PlanningAdminConsole service, modify the resource memory
allocation for Java Command Line. From \bin\ open the epPNHelperResources.
xml file and lower the memory usage in the following resource line as follows:
Original
- -
Modified
- -
Importing Text Files into Cubes
To import data into cubes, follow this process:
❑ Create the source file (p. 173).
❑ Select the cube and the text file to load into the cube (p. 175).
❑ Load the data into the datastore (p. 175).
❑ Prepare the import data blocks (p. 176).
❑ Run the Go to Production process (p. 243).
Important: If you have more than one Planning Administration Console service, you cannot use
this method for importing text files. You must load data into Import Tables (im_cubename) or
manually copy the file onto each of your servers prior to running a Prepare Import job.
Creating the Source File
If the local import file name contains any special characters, such as á or %, the Administration
Console removes or replaces them when determining the remote file name on the administration
server. You can avoid this by specifically configuring the Import Options setting in the Admin
Options window (p. 79).
The file must be in the following format:
● tab separated
● dimensions in the same order as in the IBM Cognos 8 Planning - Analyst cube
● value comes last
● no double quotation marks
Chapter 9: Managing Data
Administration Guide 173

Chapter 9: Managing Data
One million rows per e.List item per cube is a good size limit.
Import Data Source File Sample
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
Budget Version 1
174 Contributor
The following sample source file is an extract from a tab separated text file that can be used to
import data into the Corporate Expenses cube in the sample go_expenses_contributor library.
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Asia
Pacific
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Nov
Nov
Nov
Nov
Nov
Nov
Nov
Nov
Dec
Dec
Dec
Dec
Dec
Dec
Dec
Dec
Dec
613300
613500
615100
615300
615400
615500
618200
619500
613100
613200
613300
613500
615100
615300
615400
615500
618200
Communications: mobile phone
Communications: telephone
equipment
Supplies: computer supplies
Supplies: office supplies
Supplies: fax & photocopier
Supplies: catering
Services: legal
Services: recruitment
Communications: line charges
Communications: long distance
Communications: mobile phones
Communications: telephone
equipment
Supplies: computer supplies
Supplies: office supplies
Supplies: fax & photocopier
Supplies: catering
Services: legal
670
370
680
300
350
1280
14000
8000
340
450
670
370
680
300
350
1280
14000

Use the preview in the Import Data Copy tab to check that you have the source data in the correct
format.
Select the Cube and Text File to Load into the Cube
The copy process copies the import data file to a file location on the administration server and
specifies the cube that the data is to be loaded into. You can also check that your source file is in
the format expected by the datastore. The administration server destination is specified in Admin
Options (p. 79), but should be modified only by a database administrator.
If your import files are large, it is quicker to manually copy the files to the administration server
destination. If you do this, you must follow the steps described below, but do not click Copy. As
soon as you have specified a valid file and location, the Administration Console registers which file
is to be loaded into a particular cube. You can only process one import file at a time.
Steps
1. Click Development, Import Data for the appropriate application.
2. On the Copy tab, in the Select cube box, click the cube to import into.
3. In the Select text file to load box, enter the text file and its location.
4. In the Preview pane, check that the order of columns in the text file matches the order expected
by the datastore.
The header row gives the names of the dimensions taken from the cube, and the final column
(importvalue) contains the value. The rows below the heading contain the data from the text
file.
5. If the data appears to be in the wrong columns, you should rearrange the column order in the
text file and repeat steps 1-5.
6. Unless you want to manually copy the files, click Copy and then repeat steps 2 to 5 until you
have selected all the required cube and text file pairings.
The next step is to load the data.
Load the Data into the Datastore
Load the data into staging tables in the datastore, one table per cube. An import table is created
for each cube during datastore creation. There is a column for each dimension, plus a value column.
If new cubes or new dimensions are added to the Analyst model after an application is created, new
import tables or columns in the tables are created when synchronize runs and is saved.
The cube name associated with the import table is stored in the applicationobject table. The tables
are named im_cubename. Errors are stored in ie_cubename.
This process is not multi-threaded.
Chapter 9: Managing Data
Administration Guide 175

Chapter 9: Managing Data
You can also automate the loading of import files (p. 205).
Steps
1. In the Import Data window for the appropriate application, click the Load tab.
2. Select the Load check box for each cube that you want to load data for.
Row Count indicates how many rows are currently in the import table from previously loaded
data.
3. Select Delete Existing Rows if you want previously loaded data to be removed, otherwise when
the names of previously loaded data match the newly loaded data it is replaced by the new data
and previously loaded data that is not matched remains in the staging table.
4. Click Load.
The next step is to prepare the data (p. 176).
Prepare the Import Data Blocks
176 Contributor
To prepare the import data blocks, the data is taken from the import staging tables per cube, per
e.List item. The import staging table is cleared. The calculation engine validates the data and converts
it into import blocks. Errors are written to ie_cubename.
The import data block contains just the data required for an individual e.List item. Data for other
e.List items, data targeting No Data cells or formula items, and data not matching any items are
removed.
The process of converting data into import blocks uses the job architecture to run on multiple
computers and processors. It does not conflict with other online jobs for the application. Progress
logs are shown.
If you are importing a large file, you can test the import file to check that it is valid, and to avoid
time consuming problems. When you test the import file, a prepare job is created for the first e.List
item for the selected cube in the import table. Any errors are listed, such as extra dimensions,
columns in the wrong order, and invalid e.List items.
If you have more than one Planning Administration Console service, you must load data into Import
Tables (im_cubename) prior to running a Prepare Import job.
You can also automate the preparation of import files (p. 205).
Prepared Data Blocks
The Prepared Data Blocks tab displays the e.List items that have import data blocks prepared. You
must wait for the prepare import job to run before there are any prepared data blocks. The number
of data cells prepared per cube is listed for each e.List item.
Deleting the Import Queue
If you decide that you do not want to proceed with the import of data, you can click the Delete
import queue button.

Go to Production Process
If the Prepare Import process was not run, no data is imported when Go to Production is run. To
prepare import data blocks, you must cancel Go to Production and return to the Import Data
window.
Steps to Test the Import File
1. In the Import Data window for the appropriate application, click the Prepare tab.
2. In the Prepare column, select the check boxes next to the cubes that you want to test.
3. Click Test.
Any errors are listed in the Import Errors pane and a prepare import job is created. You can
view the progress of this job in the Job Management window, or in the Monitoring Console
(p. 52). If the test is successful, you can run prepare for all the import data. This overwrites
test data.
Steps to Prepare the Import File
1. In the Import Data window for the appropriate application, click the Prepare tab.
2. In the Prepare column, select the check boxes next to the cubes you are importing data into.
3. If you want import blocks created for all e.List items, and not just the e.List items that you are
importing data into, select the Zero Data option.
This zeros existing data in the cube before import takes place.
4. Click Display Row Counts to show the number of rows in the text file being imported.
5. Click Prepare.
If the Admin Option Display warning message on Zero Data is set to yes (p. 79), a warning
message is displayed if the Zero Data option is selected. This is to prevent accidental setting of
this option.
A prepare import job is created. You can view the progress of this job in the Job Management
window.
When you perform Go To Production, the prepared data will be imported.
Chapter 9: Managing Data
Administration Guide 177

Chapter 9: Managing Data
178 Contributor

Chapter 10: Synchronizing an Application
Synchronize updates all cubes in an application when the underlying objects in IBM Cognos 8
Planning - Analyst change. Changes include renaming dimensions, adding, deleting, or renaming
dimension items. Synchronize an application to re-import the definition of the cubes in the applic-
ation from Analyst. Synchronize also brings in new data for assumption cubes (that is, those cubes
without the e.List).
Before making changes to an Analyst model, you should back up the library.
Synchronizing an application means that all e.List items will be reconciled, see "Reconcili-
ation" (p. 54), after the Go to Production process is run. We recommend that you back up the
datastore before synchronizing.
Changes that Result in Loss of Data
The structure of the library is very important to a Contributor application. If changes are made to
the library in Analyst, such as deleting a dimension item, and the application is synchronized, all
data associated with that dimension item is lost.
If there is a possibility that data may be lost, you may get a warning message similar to the following:
"Destructive Synchronize detected. If you save the changes, this may result in the loss of data."
If you receive this message, you should back up your application datastore before proceeding.
A synchronize is destructive (that is, results in loss of data) in the following circumstances:
● cube dimensions were added
● cube dimensions were deleted
● cube dimensions were reordered
● detail items from a dimension were deleted
● detail items from a dimension were changed to calculated
See "How to Avoid Loss of Data" (p. 180) for more information.
If you are automating the synchronization process, you can choose to stop the process or continue
when a destructive synchronize is detected.
Administration Guide 179

Chapter 10: Synchronizing an Application
Synchronizing an Application
Synchronize an application with Analyst to ensure that all cubes that are shared with Analyst are
updated.
Steps
Generate Scripts
1. Select Development, Synchronize with Analyst for the appropriate application. A check is made
to see if you are logged on with appropriate rights. If you are not, you are prompted to log on
via the IBM Cognos Common Logon.
2. If the library or library name has changed, enter or browse for the new name in Library.
The Administration Console checks to see if the e.List selected when creating the application
still exists in the library. If it does not, a warning message appears.
3. Click Synchronize to begin the synchronization process.
A list of objects that could change is displayed, for example: which cubes were added, which
cubes were removed, which cubes had their dimensions changed, and whether dimensions were
added, deleted, or substituted.
Click Advanced to see more detailed information.
This displays detailed model information about what has changed. For more information, see
"Model Changes Window" (p. 250).
4. To save the synchronization changes, click Save.
The synchronization does not take place until Go to Production is run. If you decide not to go
ahead with the synchronize, click another part of the Administration Console without saving.
If you save, then subsequently decide to cancel the synchronization, you can click the Reset
Development to Production button on the toolbar. This discards all changes made to the
application since the last time the Go to Production process was run.
You can automate this process. For more information, see "Synchronize" (p. 205).
If the Generate Scripts option is set to Yes in Admin Options (p. 180), a check is made to see if the
datastore needs to be restructured, for example, if columns in tables must be added or deleted. If
they do, synchronize generates a script, Synchronize script.sql, when synchronize is run. This script
must be run by a database administrator. Doing so changes the columns in the ie_cubename table
just as synchronize does.
How to Avoid Loss of Data
180 Contributor
There are two ways of avoiding loss of data when you add, delete, reorder or substitute dimensions.
The method you choose depends on the size of the e.List.
The first method is to publish the production data using the View Publish Layout publish option.
The procedure for this is listed in the steps below.

An alternative method is to run a Contributor to Contributor link using Analyst. This is a simpler
process, but should only be used on applications with a small e.List.
Data is moved from the production version of a Contributor source into the development version
of the Contributor target via Analyst. Once this is complete, you must run the Go to Production
process.
Steps to Publish the Production Data
1. Make the Analyst model change.
2. Synchronize the application.
3. Click the Set offline button to take the system offline.
This takes it offline on the Web client and prevents data changing after publish begins.
4. Publish the data with No Data Dimension selected (p. 279).
5. Transfer the data from the ev_cubename view, using a tool such as DTS, depending on your
datastore. Remember to reorder/change the columns as required.
6. Run Prepare Import (p. 176).
7. Run Go to Production (p. 243).
8. Click the Set online button .
Example Synchronization
In the example shown below, the first item under Restructured Cubes, the order of the dimensions
is changed. The dimension e.List has moved from fourth to second. The preview shows the new
order of the dimensions and the old order.
Chapter 10: Synchronizing an Application
Administration Guide 181

Chapter 10: Synchronizing an Application
If you look at the expanded Product Price and Cost cube, you can see that the dimension e.List was
added to it, and in Compensation Assumptions, the dimension e.List was removed.
Under Dimensions, you can see that a dimension item (18V Trim Saw Drill/Driver Kit) was deleted
from Indoor and Outdoor Products.
Click Advanced to see more detailed information. This provides a detailed description of the differ-
ences between the previous Analyst model and the current model. It lists the cubes and dimensions
that have changed. When you click an item, a detailed breakdown of the changes is provided.
Typically, this information is used for debugging purposes.
Advanced - Model Changes
You can display the Model Changes window to see detailed information that is typically used by
technical support and development in problem solving. This report may take some time to generate.
If you have problems, you may be asked to send a file containing this information.
Steps
1. Click the Advanced button in the Synchronize window, or, during Go to Production, click the
Advanced button in the Model Changes window.
2. In the empty box at the bottom of the window, enter a file location and name and click Save.
If you compare the information that you see in Synchronize, Preview with the information that
is displayed by clicking Advanced, you will see, in the Model Changes window, one extra cube
is listed (Expenses) and an extra section named Common Links is listed. Common links contains
details of a D-Link that was changed as a result of the changes to the Compensation Assumptions
cube. The Expenses cube is listed under common cubes because it is the target of the changed
link.
Synchronize Preview
182 Contributor

Advanced--Model Changes
Chapter 10: Synchronizing an Application
Administration Guide 183

Chapter 10: Synchronizing an Application
184 Contributor

Chapter 11: Translating Applications into Different
Languages
The Translations branch enables you to translate, from an existing IBM Cognos 8 Planning - Con-
tributor application, the strings that will appear in the Web client. The translated strings are held
in the Contributor datastore along with the rest of the application and are streamed to the Web
client when the users connect to the application. In addition to creating new language translations,
you can create custom text translations.
There are three roles involved in the translation cycle:
● The model builder who creates the IBM Cognos 8 Planning - Analyst model using Analyst.
● The administrator who uses the Administration Console to create and manage the Contributor
application.
● The translator who translates the Contributor application.
If a translation is upgraded from IBM Cognos Planning version 7.3 or earlier versions, there may
be additional product strings or incompatible strings that require translation. New product strings
and incompatible strings introduced during an upgrade are not automatically filled with the base
language.
Tip: For Classic Contributor Web client users, client extensions must be configured and tested
before starting a translation.
When changes, including renaming dimensions or adding dimension links, are made to the Analyst
model, the Contributor application must be synchronized and Go to Production must be run to
incorporate the changes into the application. Any changes to the Analyst model that the Contributor
application is based on may require changes to the translation.
When the translation is opened in the Translations branch, changes to the base strings are displayed,
however, you cannot see which strings have changed. In order to see which base strings have
changed, you should export the translation from the Content Language tab both before and after
synchronizing the application, giving the translations different names. You can then compare the
translations to see what has changed.
Assigning a Language Version to a User
There are two ways of assigning a language version to a user.
● By user properties defined in IBM Cognos Configuration
If a translation exists in the language specified in the user’s product language preference prop-
erties, the user sees the application in this language.
Use this method for a straightforward translation of the model text strings and application
strings from the base language into another language.
Administration Guide 185

Chapter 11: Translating Applications into Different Languages
If a user selects a preferred product language that is not an IBM Cognos 8 Planning tier 1 lan-
guage and no translation exists, the Contributor Web client will use the model base language
for content strings and the application base language for product strings.
The application base language is configured in the Contributor Administration Console, Admin
Options, for each application.
● By user, group, or role
When creating a translation, the base language of the translation will default to the base language
of the application. The base language of the application defaults to the installation language
of the Contributor Administration Console.
You can assign a translation to a user, group, or role in the Translations branch. This method
is necessary for languages that are not supported by IBM Cognos Configuration, or if you want
to create a translation that takes account of local differences. For example you may have
European French and French Canadian versions, or US English and UK English versions.
Translate the Application
186 Contributor
You can create a new translation in the Contributor Administration Console.
Before you can translate the application, you must have translation access rights for the application.
Steps
1. In the Contributor Administration Console, expand the application to be translated so that
you can see the Translations branch.
2. Right-click Translations and click Create New Translation.
The Create New Translation dialog box appears. The system locale tells you which bitmap
fonts and code pages are defaults for the system that the Administration Console is running
on. This should be the same as the Translation Locale, otherwise the translation may not display
properly.
3. Type a translation name.
4. Select By user specified preference for Product Language, or By User, Group or Role.
Use By user specified preference for Product Language if you are creating a translation that
uses one of the supported locales. Users who have this language specified in their properties
get the translated version of the application, unless they are members of a group or role that
is assigned to a different translation.
Use By User, Group or Role to create a translation in a language that applies only to a specified
user, group, or role.
5. To select users, groups, or roles click the ellipsis (…) button.
6. Select the required namespace and then the necessary users, groups, or roles and click the add
button .
7. Click OK.

8. Select a translation locale.
This tells the operating system which code page the Contributor application uses when running
in the new language. A code page ensures that the correct character sets and keyboard layouts
are associated with the Contributor application so that it will appear properly on the user's
computer. For more information, see "System Locale and Code Pages" (p. 191).
9. Select the translation base language from English, French, German, Japanese, Finnish, and
Swedish.
10. Click Create.
The translation is added to the datastore and the strings from the Contributor application are
loaded into the Translations branch.
11. Open the new translation. To do this, click the name of the translation under Translations.
You can now begin translation.
Translate Strings Using the Administration Console
There are two parts to the translation: content language and product language.
● Content language relates to information specific to the Analyst model, which includes D-Cube
names, D-List item names, e.List items names, and model name.
Note: When you create a translation with Japanese as the base language, the content strings
are not translated. Analyst does not support Japanese characters. To use Japanese in the Con-
tributor Web client, you must translate the content strings.
● Product language relates to generic strings such as button names, status bar text, error messages,
menu and menu item names. Base strings for a language will be the same for all models.
The Content Language and Product Language tabs separate the translation items into categories.
The total category on the Product Language tab is used when a multi-e.List view is displayed for
all contributions. There are a number of categories that appear on the Product Language tab if client
extensions are installed. These allow you to translate the buttons, wizards and any messages that
the user might see.
The strings are color coded to indicate the status of the string. The colored squares in the Category
column have the following meanings:
● Blue - the translated string cell has not changed in this session.
● Red - the translated string cell has changed in this session.
● White - the translated string cell is empty.
If strings on the Content Language tab are left blank, they will default to the base string in the Web
application. If strings on the Product Language tab are left blank, they will appear blank in the
Web application.
Chapter 11: Translating Applications into Different Languages
Administration Guide 187

Chapter 11: Translating Applications into Different Languages
188 Contributor
If you do not have the correct system locale set on your computer, we recommend that you export
the file in .xls format, and use Excel to translate the strings. This ensures that the fonts appear
correctly when you are translating. For more information, see "Export Files for Translation" (p. 190).
In Product Language, some of the translatable strings contain parameters that must not be changed,
for example:
%1:currently annotating user% has been annotating %2:e.List
item% since %3:edit start time%.\r\nIf you continue and annotate
then %1% will be unable to save any changes.\r\nDo you still wish
to annotate %2%?
The following are parameters:
● %1:currently annotating user%
● %2:e.List item%
● %3:edit start time%
You cannot add, remove, or edit parameters. However, they can be moved or repeated within the
translation string.
These are some of the formatting codes that are used:
Code
\r
\n
\t
Description
carriage return
new line
tab
For example:
Unable to create email :-\r\n\tTo: %1:to%\r\n\tCc: %2:cc%\r\n\tSubject:
%3:subject%\r\n\tBody:
%4:body%
Text in message boxes wraps automatically so it is not always necessary to use formatting codes.
Steps
1. In the Translations branch, click the name of the translation.
2. Click the Content Language tab or Product Language tab.
3. Enter the new strings directly in the Translated string column or into the Edit window. You
can choose to:
● Populate the empty column with the text in the Base string column and then edit the text.
To do this, right-click in the column and click Copy base to translated.
● Click on the first base string that you are going to translate. This will appear in the left
pane of the Edit window. Enter or edit the translated text in the right pane. Populate any
remaining blank cells with base string text if this is needed. To do this, right-click in the
column and click Fill empty with base.

You can clear strings from the Translated string column by right-clicking and selecting Clear
translated.
4. Save the translation.
A warning about empty translation strings only applies to the active tab. The translation will
not appear correctly in the Web application if there are any empty content or product strings.
Exporting and Importing Files for Translation
If you want to translate the Contributor application outside of the Administration Console, you
can use the import and export functions.
You can import and export files in the following formats:
● tab delimited text
● xls
● xml
Define an Excel worksheet (import only).
● other
Define a custom format.
Files that you import must match the format expected by the Administration Console. The best
way to ensure this is to first export a file in the format that you will be editing in. After you have
completed your translation, import the changed file.
Import File Format
The format needed for import is:
String ID Context Base Translation Hint
Where:
String ID
Context
Base
Translation
A unique identifier given to an object.
This should not be changed.
Groups the parts of the application into sections, for example, Model, D-
Cube, Hierarchy.
This should not be changed.
The string to be translated in the language in which the model was first cre-
ated.
This should not be changed.
This is the translated string.
This can be changed.
Chapter 11: Translating Applications into Different Languages
Administration Guide 189

Chapter 11: Translating Applications into Different Languages
Hint
Export Files for Translation
This is a hint to help the translator.
To translate the Contributor application outside of the Administration Console, you can export a
file for translation.
Steps
1. Open the translation and click either the Content Language tab or the Product Language tab.
Only one tab can be exported at a time.
2. Click Export.
3. Enter a file name and location.
4. Select the required file format. If you click Other, you must enter a custom delimiter, for example
";".
5. Select Include column headers if you want to include a header row. This is useful for files that
you may be opening in a tool such as Excel. It lets you see which text contains the translated
strings.
If you are modifying the export file to import it into the Administration Console, you should
only edit the text in the Translation column. If you edit the text in the String ID, Category, or
Base columns, you will have problems importing the file.
6. Click OK.
Import Translated Files
190 Contributor
After you have completed your translation, you can import a translated file.
Steps
1. Open the translation into which you are going to import the translated file.
2. Click either the Content Language or the Product Language tab.
Select the same tab that you originally exported the file from.
3. Click Import.
4. Select the appropriate file format.
If you select xls, you should enter the worksheet name in the Excel worksheet box. If you select
Other, enter a delimiter in the Delimiter box.
5. Click the First row contains field names option if applicable.
6. Enter the file name and location in the File name box and click OK.
7. Click Save.

Search for Strings in the Content Language or Product Language
Tab
You can search for strings in either the Content Language or Product Language tab using search
criteria.
Steps
1. Click Find.
2. Select the search criteria:
Criteria
Find what
Search All Categories,
Selected Rows
Direction
Search in
Translating Help
Description
Enter the text string. Previous searches are saved and you
can select them from the list.
Select whether you want to search all categories, or selected
rows.
Select the direction for the search, either Up or Down
(default).
Choose whether you want to search in translated string or
base string.
3. To begin the search, click Find next.
You can translate Contributor help text in the same way that you translate other strings.
Cube help is located on the Content Language tab under Cube help for . The first row
has simple cube help, the second row is detailed cube help that may contain HTML tags. These
tags can be modified.
Instructions are also located on the Content Language tab under Application Headline and
Instructions. The top row is the headline and the bottom line is the instructions.
It is not possible to translate the default help supplied with the Contributor Web site from the
Contributor Administration Console.
System Locale and Code Pages
Chapter 11: Translating Applications into Different Languages
Before you begin translation, there are some issues you must consider. When you create a new
translation, you select a translation locale to be associated with the translation. The translation
locale tells the system which code page the Contributor application uses when running in the Web
client. The code page is a table that relates the binary character codes used by a program to keys
Administration Guide 191

Chapter 11: Translating Applications into Different Languages
About Fonts
192 Contributor
on the keyboard or to characters on the display and is used to ensure that text appears in the
appropriate language, as determined by the system locale of the computer. The available system
locales are determined by the installed language groups, which enable programs to show menus
and dialogs in the user’s native language.
When you create the translation, a check is run to ensure that the translation locale ID matches
that of the system locale and the code page. If it does not match, a warning is issued. This is because
the strings are not displayed in the Translations branch in the same way as they are in the Web
client. Any double-byte strings that contain characters that are not contained in the code page will
not be shown in that code page (typically they will appear as "?"). Even though the characters do
not appear correctly, this is only a display problem. The characters are stored correctly internally.
If you do not want to change the system locale to that of the language you are translating to, you
can export a text file containing the client strings and translate the strings using Excel. Excel handles
languages very well and you will see them appear correctly. You should then save the file in .xls
format, import it to the Translations branch, and click Save.
A font has both a name and a set of charsets that it supports. Some fonts support a variety of
charsets from the Unicode range and some do not. Some, such as MS Sans Serif, are not Unicode
fonts and only support the Western code pages.
Japanese has limited support from the set of fonts that are installed by default on a US/English
version of Windows 2000/XP. None of the standard fonts supplied with Windows 2000 support
the Japanese charset.
Once you install the Japanese language pack, however, standard Japanese fonts are installed on
your system (Japanese fonts all have unique names).
For Korean or Japanese translations to appear correctly in the Contributor Web client, you must
set them as the default character set for the operating system.
Tip: You can install fonts for East Asian languages through Regional and Language Options in the
Windows Control Panel.

Chapter 12: Automating Tasks Using Macros
You can automate common tasks that are performed in Contributor Administration Console by
using macros. Formerly known as Automation Scripts and created by the Contributor Automation
tool, the automation of tasks is now integrated with Contributor Administration Console using
macros and macro steps. This makes it easier to maintain and use automated tasks.
Macros, comprised of macro steps, can be
● run interactively within Contributor Administration Console
● triggered by events, such as the submitting of data
● scheduled to run in IBM Cognos Connection
● using the Windows Command line interface
● using Windows scripts and batch files via a batch scheduling tool
Macros are stored in the Planning content store. Macros and macro steps can be exported and
imported again as an XML file.
❑ Create a new macro, see (p. 194).
❑ Run a macro from the Administration Console (p. 225), from IBM Cognos Connection (p. 225),
as an IBM Cognos 8 Event (p. 226), from the command line (p. 228), or as a batch file (p. 228).
❑ Set access rights for macros, (p. 42).
❑ Troubleshoot macro errors, (p. 229).
Common Tasks to Automate
Using the Contributor Administration Console, you can group related tasks into a single macro to
execute them in sequence. Macros can be run in the Administration Console, or by using external
scheduling tools.
For example, you can automatically
● import an e.List and rights from files
● run administration links
● import simple (non-rule based) access tables
● synchronize with Analyst
● publish only changed data
The following are examples of tasks in the Administration Console that are performed frequently
and are often automated using either Macros or a batch scheduler tool.
Administration Guide 193

Chapter 12: Automating Tasks Using Macros
Task
Import and Process Data
Update Application with External
Changes
Month End (Move data to other sys-
tems)
Creating a Macro
Create a New Macro
194 Contributor
Macro Steps included
File (repeated for each Cube)
Prepare Import
Go To Production
Synchronize
Import e.List
Import Rights
Import Access Table
Go to Production
Set an Application Offline
Execute Administration Link
Publish
Create macros using the Macros tool in Contributor Administration Console. Macros are used to
automatically perform tasks. Macros are stored in the Planning store.
❑ Create a new macro (p. 194)
❑ Create a macro step (p. 195) or transfer macro steps from another macro (p. 198)
Create a new macro to create an automated task. Macros published to IBM Cognos Connection
can be run or scheduled from the Content Administration area of IBM Cognos Administration or
used to create an event or job.
Steps
1. In the Contributor Administration tree, click the Macros icon .
2. Click New.
3. In the Macro Name box, type the name of the new macro. Click the Publish to IBM Cognos
Connection check box to have the macro accessible in IBM Cognos Connection and click OK.
The new macro appears in the Macros box. The Edit State is set to Incomplete because no steps
are added yet, and the Run State is set to Ready.
Tip: Rename or delete a macro by selecting the macro in the Macros list and clicking Rename
or Delete.

Create a Macro Step
Function to automate
Job Servers
Add a container to a job server
Use macros to group and run a number of macro steps in the specified sequence. A macro step holds
the parameters for the macro. For example, you want to run the following tasks to import some
data: Wait for Any Jobs, Load Import Data, Prepare Import, and Go to Production.
Automation scripts used in the Contributor 7.2 Automation tool are matched to the macros used
in the current Contributor Administration Console.
Note: The Automation scripts created in version 7.2 and earlier cannot be used as macro steps.
Stop a job server at a scheduled time
Start a job server at a scheduled time
Generate a report on jobs in a con-
tainer
Remove a container from a job server
Control the maximum number of
jobs that can run on a job server
Set how often a job server checks for
jobs
Schedule other macro steps to allow
any jobs to finish before other jobs
start
Development
Take the development Contributor
application and create a production
application
Move data from import staging tables
Load data into the datastore staging
table
Type of macro step
Add Monitored Job Object
(p. 199)
Disable Job Processing (p. 199)
Enable Job Processing (p. 199)
Job Doctor (p. 200)
Remove Monitored Job Object
(p. 200)
Set Max Concurrent Job Tasks
(p. 201)
Set Polling Interval for Job Server
(p. 201)
Wait for Any Jobs (p. 201)
Go to Production (p. 202)
Prepare Import (p. 205)
File (p. 204)
Chapter 12: Automating Tasks Using Macros
7.2 automation script name
AddMonitoredApplications.xml
StopApplicationServer.xml
StartApplicationServer.xml
JobDoctor.xml
RemoveMonitoredApplications.xml
SetMaxConcurrentJobTasksFor
ApplicationServer.xml
SetPollingIntervalForApplication-
Server.xml
WaitForAnyJobs.xml
AutomatedGoToProduction.xml
AutomatedPrepareImport.xml
UploadImportFile.xml
Administration Guide 195

Chapter 12: Automating Tasks Using Macros
Function to automate
Synchronize Analyst and Contributor
Run an Analyst Macro
Import Access Tables into a Contrib-
utor application
Import an e.List into a Contributor
application
Import rights into a Contributor
application
Run an existing Deployment Import
or Deployment Export
Load the development model XML
into a development application
Production
Publish data collected by Contributor
to a datastore (using default paramet-
ers)
Publish data collected by Contributor
to a datastore (configuring all para-
meters)
Publish data collected by Contributor
to a datastore for reporting purposes
Publish only changed data for e.List
items
Delete user or audit Commentary
Run an Admin Extension in a Con-
tributor application
Set a Contributor application online
or offline
Administrator Links
196 Contributor
Type of macro step
Synchronize (p. 205)
Execute Analyst Macro (p. 206)
Import Access Table (p. 206)
Import e.List (p. 208)
Import Rights (p. 209)
Run Deploymnet (p. 210)
Upload a Development Model
(p. 210)
Publish - View Layout (p. 212)
Publish - View Layout - Advanced
(p. 212)
Publish - Table Only Layout
(p. 214)
Publish - Incremental Publish)
(p. 216)
Delete Commentary (p. 217)
Execute an Admin Extension
(p. 218)
Set an Application Online or Off-
line (p. 219)
7.2 automation script name
N/A
N/A
N/A
N/A
N/A
N/A
UploadDevelopmentModel.xml
N/A
AutomatedPublish.xml
N/A
N/A
DeleteAnnotations.xml
ExecuteAdminExtension.xml
UpdateWebClientBarrier.xml

Function to automate
Run an Administration Link in a
Contributor application
Macros
Generate debugging report for mac-
ros
Test a macro
Run a macro
Run a program from the command
line
Import a macro
Export a macro
Session
Remove an application lock
Steps
Type of macro step
Execute an Administration Link
(p. 219)
Macro Doctor (p. 221)
Macro Test (p. 221)
Execute Macro (p. 221)
Execute Command Line (p. 222)
Import Macros from Folder
(p. 222)
Export Macros to Folder (p. 223)
Remove Application Lock (p. 223)
1. In the Macro Steps area, click New.
The Select new macro step type dialog box appears.
2. Click the type of macro step you want to add.
3. Click OK.
7.2 automation script name
N/A
N/A
N/A
Test.xml
A dialog box appears with the parameters relevant to the type of macro step you selected.
4. Review each parameter and change it as required. For information about the parameters, see
N/A
N/A
N/A
N/A
N/A
the topic for the type of macro step you are adding in step 2.
5. Click Validate. This checks the validity of the parameters.
6. If you want to add other steps to the macro, click New and repeat steps 2 to 5 for each macro
step.
7. When you are done, click OK.
Chapter 12: Automating Tasks Using Macros
The macro steps are added to the list of macro steps contained in the macro.
Tips: To edit or delete a macro step, click the macro step and click Edit or Delete. To reorder
macro steps, click the macro step and then click the Move Up or Move Down button.
Administration Guide 197

Chapter 12: Automating Tasks Using Macros
Transferring Macros and Macro Steps
198 Contributor
You can copy steps from one macro to another, create a backup copy of your macro, add steps to
another macro, and make a copy of an existing macro.
Steps
1. Click the Macros icon in the tree.
2. In the Macros list, select the Macro and click Transfer.
3. Configure the following properties:
Property
Direction
From
To
Delete Source
Copy From
Other Macro
New Macro
(self)
Files in Folder
Publish to IBM Cognos
Connection
Select Steps
All Steps
Specify Steps
4. Click OK.
Description
Exports a macro step from the existing macro
Imports a macro step into the existing macro
Deletes the macro step from the original macro
Copies the selected macro step to another macro
Creates a new macro that includes the selected macro step
Makes a copy of the selected macro step in the existing macro
Copies the selected macro step to a folder, which is used for
backup purposes
Publishes the macro to IBM Cognos Connection for use in Event
Studio.
Selects all macro steps in the macro
Specifies which macro steps to include in the transfer

Job Servers (Macro Steps)
Add Monitored Job Object
Job servers can be managed using macro steps. Macro steps can do things such as enable or disable
job processing and set polling intervals.
For more information about managing job servers, see "Manage a Job Server Cluster" (p. 56).
Use this macro step to automate the addition of a container to a job server. It works with the
Remove Monitored Job Object macro step. You can schedule the addition and removal of job
objects from job servers at a time that is appropriate for your business.
In Contributor, an application can run on more than one job server. The administrator adds a job
server to Contributor Administration Console, and then adds applications to the job server. The
administrator can start and stop job servers from Administration Console, but cannot start and
stop individual applications.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Job Server or Cluster
Job Container
Disable Job Processing
Description
The name of the macro step.
Browse to the Job Server or Cluster that you want to start by clicking
the Browse button and selecting the correct server name.
The container you want to monitor.
Use this macro step to stop a job server at a scheduled time.
The following table describes the relevant parameters.
Parameter
Enable Job Processing
Macro Step Name
Job Server or Cluster
Description
The name of the macro step.
The job server or cluster that you want to stop.
Use this macro step to start a job server at a scheduled time.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Description
The name of the macro step.
Chapter 12: Automating Tasks Using Macros
Administration Guide 199

Chapter 12: Automating Tasks Using Macros
Job Doctor
Parameter
Job Server or Cluster
Description
The job server or cluster that you want to start.
Use this macro step to generate a report on jobs in a container. The report is in XHTML format.
It is typically used on the advice of Technical Support and can be used to help debug problems with
Contributor jobs.
Tip: Adding a Wait for Any Jobs macro step before the Job Doctor macro step ensures that all jobs
are complete before moving on to this macro step. For more information on the Wait for Any Jobs
macro step, see "Wait for Any Jobs" (p. 201).
The following table describes the relevant parameters.
Parameter
Macro Step Name
Job Container
Include contents of
Admin History
Report file name (Enter
Local Application Server
Path)
Remove Monitored Job Object
200 Contributor
Description
The name of the macro step.
The container you want to report on.
Whether to include the adminhistory table information in the report.
Although this is useful information, it can slow down report generation
and make the output quite large.
A path and file name for the XHTML report.
Use this macro step to automate the removal of a container from a job server. It is the converse
macro step to the Add Monitored Job Object macro step. You can schedule the addition and removal
of applications from job servers at a time that is appropriate for your business.
In Contributor, an application can run on more than one job server. The administrator adds a job
server to Contributor Administration Console, and then adds applications to the job server. The
administrator can start and stop job servers from Administration Console, but cannot start and
stop individual applications.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Job Server or Cluster
Description
The name of the macro step.
Browse to the Job Server or Cluster that you want to stop by clicking
the Browse button and selecting the correct server name.

Parameter
Job Container
Set Max Concurrent Job Tasks
Description
The container you want to stop monitoring.
Use this macro step to control the maximum number of jobs that can run on a job server. This is
useful if the computer is slow or you must run other non-Contributor applications on the server at
the same time.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Job Server or Cluster
Maximum number of Job
Tasks
Set Polling Interval for Job Server
Wait for Any Jobs
Description
The name of the macro step.
The job server or cluster that you want to limit job tasks on.
The maximum number of job tasks allowed. This should be no more
than the number of physical processors that you have on the computer.
Use this macro step to set how often a job server checks for jobs. The default is 15 seconds. Use
this macro step to control the amount of resources used by the job service.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Job Server or Cluster
Polling Interval
Description
The name of the macro step.
The job server or cluster that you want to set polling interval for.
Set the frequency with which a job server looks to see if there are any
jobs to do. This is measured in seconds. The default is 15 seconds.
Use this macro step to ensure jobs are completed before allowing processing to continue. This macro
step is especially useful when combining it with other macro steps that may not wait for all jobs to
run before beginning, such as the Go To Production macro step.
You can monitor the jobs in a container.
The following table describes the relevant parameters.
Chapter 12: Automating Tasks Using Macros
Administration Guide 201

Chapter 12: Automating Tasks Using Macros
Parameter
Macro Step Name
Job Container
Job Timeout (in minutes)
Development (Macro Steps)
Go to Production
202 Contributor
Description
The name of the macro step.
The container you want to monitor.
A time period after which the macro terminates with an error if the
jobs are not completed. The default is 1440 minutes, which is one
day.
Development tasks can be managed using macro steps. Macro steps can do things such as run the
Go to Production process, import access tables, e.Lists, and rights into a Contributor application,
and move data from or load data into staging tables.
The Go to Production process takes the development Contributor application and creates the pro-
duction application, making it available to users on the Web client. A new development application
is established. Use this macro step to automate the Go to Production process.
Before you can run Go to Production, the application must at least have an e.List and users defined.
You can run Go to Production without setting any rights, but no one can view the application on
the Web client. However, you can preview the application by selecting Production, Preview in the
Administration Console.
When you start Go to Production, job status is checked. If jobs are running or queued, the Go To
Production macro step will wait for them to complete. During the automated Go to Production
process, the following checks are completed.
● A check is made to see if there are any jobs running.
● If necessary, a job is created to ensure that all e.List items are reconciled if they are not already.
● A check is made to see if a Cut-down models job is required. If it is required, the job is created
and run.
For more information on Go To Production, see "The Go to Production Process" (p. 243).
The following table describes the relevant parameters.
Parameter
Macro Step Name
Application
Create Planning package
Description
The name of the macro step.
The name of the Contributor application datastore that the macro
step is being run against.
Publish the Planning package to IBM Cognos Connection.

Import Data
Parameter
Reset e.List Item States
Minimum e.List Item
Description
State: ● Not Started
Maximum e.List Item
One of the following minimum workflow states
● Work in Progress
● Locked
If you set the minimum workflow state to Work in Progress, any e.List
items that have a workflow state of Not Started are reset to Work in
Progress. The default is Not Started, which means no change takes
place.
State: ● Not Started
Skip Top Level e.List Items
Jobs
Job Timeout (in minutes)
Wait for jobs after Go to
Production
Validation Report
One of the following maximum workflow states
● Work in Progress
● Locked
The state must be greater than or the same as the minimum e.List
Item State.
If you set Work in Progress, and e.List items are Locked, the e.List
items are reset from Locked to Work in Progress.
The default is Locked, which means no change takes place.
Does not reset top level e.List items.
A time period after which the macro step terminates if the preexisting
jobs are not completed. If jobs are running, Go to Production will
wait for them to finish. The default is 1440 minutes, which is one
day.
After the Go to Production process, complete all jobs before moving
on to the next macro step.
Indicates problems with parameters set in the Go to Production pro-
cess. Click Validate to recheck the validation report status.
Importing data into cubes requires the following process.
● Create the source file.
Chapter 12: Automating Tasks Using Macros
Administration Guide 203

Chapter 12: Automating Tasks Using Macros
204 Contributor
● Select the cube and text file to load into the cube.
● Load data from the text files into the datastore staging tables.
● Prepare the import data blocks.
● Run the Go to Production process.
For more information on importing data, see "Managing Data" (p. 143).
Two macro steps are provided for the import process: Upload Import File and Prepare Import.
Upload an Import File
Use this macro step to load data from a text file into the datastore staging table. You can load only
one file at a time using this macro step.
An import table is created for each cube during datastore creation. There is a column for each
dimension, plus a value column. If new cubes or new dimensions are added to the Analyst model
after an application is created, new import tables or columns in the tables are added after a syn-
chronize is run and saved.
The cube name associated with the import table is stored in the application object table. The tables
are named im_cubename and ie_cubename. Errors are stored in ie_cubename.
Files can be loaded from any location that your bulk load engine supports.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Application
File to Upload (Enter
Local Application
Server Path)
Target Cube Name
Remove existing data
in import table
Description
The name of the macro step.
The name of the Contributor application datastore that the macro step is
being run against.
The name and location of the file to be loaded. This can be a UNC location
such as \\server\share\file.txt.
The name of the cube that the data is to be imported into.
Whether existing rows are to be deleted. Selecting this item removes previ-
ously loaded data. Clearing this option when the names of previously
loaded data match the newly loaded data causes the new data to replace
the old. Previously loaded data that is not matched remains in the staging
table.

Synchronize
Prepare Import
Use this macro step to take the data from the import staging tables per cube, per e.List item. The
calculation engine validates the data and converts it into import blocks Errors are written to
ie_cubename.
The import data block contains only the data required for an individual e.List item. Data targeting
No Data cells or formula items and data not matching any items is removed.
The process of converting data into import blocks uses the Job architecture to run on multiple
computers and processes. It will not conflict with other online jobs for the application.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Application
Cube Details
Cubes to Prepare
Cubes to Zero
Job Timeout (in
minutes)
Description
The name of the macro step.
The name of the Contributor application datastore that the macro step
is being run against.
The names of the cubes that you are going to prepare import data for.
The names of the cubes that you are going to prepare import data for.
A time period after which the macro step terminates if the job is not
completed. If the job does not succeed, an error appears. The default is
1440 minutes.
Use this macro step to automate the synchronize function for the application.
For more information on synchronizing an application, see "Synchronizing an Application" (p. 179).
The following table describes the relevant parameters.
Parameter
Macro Step Name
Application
Analyst Library Name
Description
The name of the macro step.
The name of the Contributor application datastore that the macro step
is being run against.
Chapter 12: Automating Tasks Using Macros
The name of the Analyst Library to synchronize. Either use library name
already specified for the application or select other library name.
Administration Guide 205

Chapter 12: Automating Tasks Using Macros
Parameter
Save Changes if
Destructive
Execute Analyst Macro
Import Access Table
206 Contributor
Description
Destructive synchronize removes dimensional items or cubes and results
in data loss.
When you run the synchronize process from the Contributor Administra-
tion Console, you can preview the changes and decide whether to save
the synchronization. When running synchronize using macros, it is not
possible to preview the changes before saving the synchronize. Instead,
you can choose to cancel the synchronization if data will be lost by
selecting the Save changes if destructive option.
A synchronize is considered destructive in the following circumstances:
● cube dimensions added
● cube dimensions deleted
● cube dimensions substituted
● cube dimensions reordered
● detail items from a dimension deleted
● detail items from a dimension changed to calculated
For more information, see "Changes that Result in Loss of Data" (p. 179).
Use this macro step to execute an Analyst Macro. For more information on Analyst macros, see
the Analyst User Guide.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Analyst Macro
Description
The name of the macro step.
The Analyst Library containing the macro you want to run and the specific
macro.
Use this macro step to import Access Tables into your application.
For more information on Access Tables, see "Access Tables" (p. 119).
The following table describes the relevant parameters.
Parameter
Macro Step Name
Description
The name of the macro step.

Parameter
Application
Base access level
Access Table Name
(import only)
Access Table File Path
(Enter Local Applica-
tion Server Path)
Trim leading and trail-
ing whitespace
First row is heading
Delete Undefined items
File Type
Text File
Quoted Strings
Delimiter
Excel File
Errors and Warnings
Stop if warnings or
errors returned from
import
Description
The name of the Contributor application datastore that the macro step
is being run against.
Choose from:
● No Data
● Hidden
● Read
● Write (default)
The Access Table name.
The path for the Access Table file.
Whether you want to remove leading and trailing whitespace in the file.
Whether the first row is used as the header row.
If an access table file was previously imported for the access table, and
you are importing a new one, existing settings are updated with the new
specified settings. Select this check box to delete settings that do not exist
in the new file. If the check box is cleared, previous settings are retained.
Whether you are importing a text file.
Whether the file has quoted strings.
The type of delimiter the file uses.
Whether you are importing an Excel file. Enter the Worksheet location.
Whether you want the macro to stop or not if a warning or error is
returned from the import.
Chapter 12: Automating Tasks Using Macros
Administration Guide 207

Chapter 12: Automating Tasks Using Macros
Parameter
Log File Path
Add this extension to
the import file path
Specify Log File Path
(Enter Local Applica-
tion Server Path)
Import e.List and Rights
208 Contributor
Import e.List
Description
Specify the extension you want for the log file name. For example: Log
Specify a local application server path for where you want the log file to
be saved.
For more information on the e.List, see "Managing User Access to Applications" (p. 93).
Use this macro step to import an e.List into your application.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Application
e.List File Path (Enter
Local Application
Server Path)
Trim leading and trail-
ing whitespace
First row is heading
Delete Undefined items
File Type
Text File
Quoted Strings
Description
The name of the macro step.
The name of the Contributor application datastore that the macro step
is being run against.
The location of the e.List file.
Whether you want to remove leading and trailing whitespace in the file.
Whether the first row is used as the header row.
If an e.List was previously imported and you are importing a new e.List,
existing settings are updated with the new specified settings. Select this
check box to delete settings that do not exist in the new file. If the check
box is cleared, previous settings are retained.
Whether you are importing a text file.
Whether the file has quoted strings.

Parameter
Delimiter
Excel File
Errors and Warnings
Stop if warnings or
errors returned from
import
Log File Path
Add this extension to
the import file path
Specify Log File Path
(Enter Local Applica-
tion Server Path)
Import Rights
Description
The type of delimiter the file uses.
Whether you are importing an Excel file. Enter the Worksheet location.
Whether you want the macro to stop or not if a warning or error is
returned from the import.
Specify the extension you want for the log file name. For example: Log
Specify a local application server path for where you want the log file to
be saved.
Use this macro step to import rights into your application.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Application
Rights File Path (Enter
Local Application
Server Path)
Trim leading and trail-
ing whitespace
First row is heading
File Type
Text File
Description
The name of the macro step.
The name of the Contributor application datastore that the macro step
is being run against.
The location for the Rights file.
Whether you want to remove leading and trailing whitespace in the file.
Whether the first row is used as the header row.
Whether you are importing a text file.
Chapter 12: Automating Tasks Using Macros
Administration Guide 209

Chapter 12: Automating Tasks Using Macros
Run Deployment
Parameter
Quoted Strings
Delimiter
Excel File
Errors and Warnings
Stop if warnings or
errors returned from
import
Log File Path
Add this extension to
the import file path
Specify Log File Path
(Enter Local Applica-
tion Server Path)
Description
Whether the file has quoted strings.
The type of delimiter the file uses.
Whether you are importing an Excel file. Enter the Worksheet location.
Whether you want the macro to stop or not if a warning or error is
returned from the import.
Specify the extension you want for the log file name. For example: Log
Specify a local application server path for where you want the log file to
be saved.
Use this macro step to run a Deployment Import or Deployment Export.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Select the Request to
run
Upload a Development Model
210 Contributor
Description
The name of the macro step.
Navigate to the deployment that you want to run.
Use this macro step to load the development model XML into a development application. For
information about saving the Development XML, see "Save Application XML for Support" (p. 79).
Remove write access in the Contributor Administration Console from the current user before running
the macro step. This macro step typically is used if you are running parallel test and live servers
and you need to upload the XML from the test server to the live server. On the target server, there
must be an existing application. After the development model has been uploaded, Go to Production
must be run for the model to appear to Web users.
This should be used only on the advice of Technical Support.

The following table describes the relevant parameters.
Parameter
Macro Step Name
Application
Model Definition File Path
(Enter Local Application
Server Path)
Save any generated datastore
scripts to file
Production (Macro Steps)
Publish
Description
The name of the macro step.
Enter the name of the Contributor application datastore that the
macro step is being run against.
The name and location of the model definition file. The model
definition file is a description of the entire Contributor application
and is in XML format.
A location for generated datastore scripts to be saved.
When Generate Scripts is set to Yes in Admin Options, a check
is made to see if the datastore must be restructured, for example,
if tables must be added or deleted, a script is generated.
This datastore update script typically must be run by a database
administrator (DBA).
Production can be managed using macro steps. Macro steps can do things such as enable automated
publishing or modify publish layouts.
Use the Automated Publish process when you need to perform a Contributor publish as a scheduled
task or from the command line as part of a script. A Publish can no longer target the Contributor
transactional datastore.
During the publish process, the published data is exported to a temp directory on the job servers.
A file is created for each e.List item for each cube. After the files are created, they are typically
loaded to the datastore using a bulk load utility (BCP or SQLLDR) and then the temp files are
deleted.
Using the Publish - View Layout - Advanced macro step, you can do an interruptible publish if you
want to use different mechanisms to bulk load data into the target datastore or an external applic-
ation. Interruptible publish prevents the temp files from being loaded into the datastore and deleted.
They remain in the temp directory, or you can collate them into a large file per cube. For collation,
each job server that may be involved in the publish job must expose a share that the computer
running the macro step can access. That share must expose the TEMP folder for the user context
of the Planning Service.
Tip: To use Interruptible publish, you must select from the How should the data be managed option
group the User-managed option.
For more information on publishing, see "Publishing Data" (p. 259).
Chapter 12: Automating Tasks Using Macros
Administration Guide 211

Chapter 12: Automating Tasks Using Macros
212 Contributor
Publish - View Layout
Use this macro step instead of the Publish-View Layout-Advanced macro step when you do not
need to change any of the default parameters set for the Publish-View Layout-Advanced macro
step.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Select Publish Container
Suppress zeros
Cubes to Publish
e.List items to Publish
Description
The name of the macro step.
Select a container to publish the data to.
Whether to publish zeros.
Selecting this option suppresses zeros. This can speed up the process
of publishing data substantially, depending on the number of blank
cells.
Publish - View Layout - Advanced
Whether to publish all or some Contribution cubes.
Whether to publish all e.List items, use the selection from Contributor
Administration Console, or select individual e.List items.
This macro step automates the view layout publish process. This layout is for historical purposes.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Select Publish Container
Use Plain Number Formats
Data Filters
Description
The name of the macro step.
Select a container to publish the data to.
Whether numeric formatting is removed or retained. Selecting this
option removes any numeric formatting. It publishes data to as many
decimal places as needed, up to the limit stored on the computer.
Negative numbers are prefixed by a minus sign. There are no thousand
separator, percent signs, currency symbols, or other numeric formats
that are applied on the dimension or D-Cube. Plain Number Format
uses the decimal point (.) as the decimal separator.

Parameter
Suppress zeros
Data access level to pub-
Description
Whether to publish zeros.
Selecting this option suppresses zeros. This can speed up the process
of publishing data substantially, depending on the number of blank
cells.
lish ● No data
Annotation Filters
How should the data be
managed?
Automatically upload data
to datastore
Remove existing data
Where should the data be
published to?
User Managed
Publish GUIDs not Names
(to upload to export
tables)
Should files be collated
The access level of data to Publish, one of
● Hidden (default)
● Read
● Write
This option is additive, so if you select Hidden, data set to Read and
Write is also published, and if you select Read, data set to Write is
also published.
The type of annotations to be published.
Whether to load data automatically into the datastore.
Selecting this option ensures that a consistent set of data is published.
It publishes data for all the selected cubes, and removes all other
published data in the datastore. Clear this option if you want to leave
existing data. If an e.List item is being republished, it replaces data
for that e.List item with the new data.
Whether to publish to either a default container or an alternate publish
container.
Whether to take control of the published data.
Select this item if you are doing a standard publish because the GUIDs
are used to load the data into the publish tables. You may want to
use names rather than GUIDS if the data is to be exported to Analyst
or external systems.
Chapter 12: Automating Tasks Using Macros
If Yes, enter location for Local Application Server and enter the share
name to retrieve files from. This share must exist on all machines that
process the job. The same share name is used for all machines.
Administration Guide 213

Chapter 12: Automating Tasks Using Macros
214 Contributor
Parameter
Cubes to Publish
Stop execution if specified
Cubes not found
Select e.List items
Stop execution if no e.List
items result from settings
e.List items to Publish
Stop execution if specified
e.List items not found
Apply Filters to e.List
items
Publish e.List items
changed since
e.List item type
e.List item state
Job Timeout (in minutes)
Publish - Table Only Layout
Description
Whether to publish all or specific Contribution cubes.
Selecting this option ensures that execution and processing will be
halted when there are no Cubes that can be identified from the results
of the selected settings.
Selecting this option ensures that execution and processing will be
halted when there are no e.List items that can be identified from the
results of the selected settings.
Whether to publish all e.List items, use the selection from Contributor
Administration Console, or select individual e.List items.
Selecting this option ensures that execution and processing will be
halted when there are no e.List items that can be identified from the
results of the selected settings.
Enter or select a date and time for filtering those e.List items that have
since changed.
One of the following:
Contributor
Reviewer
Reviewer or Contributor (default)
Whether to publish e.List items at any state or specify a particular
state to publish.
A time period after which the macro step terminates if the job is not
completed. If the job does not succeed, an error appears. The default
is 1440 minutes, or one day.
This macro step automates the table - only layout publish process. This layout is required for the
Generate Framework Manager Model extensions and the Generate Transformer Model extension
(Analyst and Contributor versions for both).
The following table describes the relevant parameters.

Parameter
Macro Step Name
Select Publish Container
Use persisted parameters
for all settings
Data options/ Column
Options
Create columns with data
types based on the 'dimen-
sion for publish'
Only create the following
columns
Include rollups
Include zero or blank val-
ues
Prefix column names with
data type
Table options
Include user annotations
Include audit annotations
Include attached docu-
ments
Description
The name of the macro step.
Select a container to publish the data to.
Whether to use same parameters for all settings for each time macro
step is run.
Determines the column data types from the model using the selected
'dimension for publish'. This option can minimize the default number
of columns although non-uniform data will not be published. For
example, row data will be filtered when a value is inconsistent with
the model and column data type.
This option will always publish the selected columns from the
'dimension for publish'. Use this option to publish only the required
data of the selected types. Selecting numeric, date and text options
will ensure all data (uniform and non-uniform) is published.
Selecting this check box includes all items, including calculated items.
Clearing this option only publishes leaf items, and therefore fewer
rows. You can recreate the calculation in your reporting tools by
linking the et and sy tables.
Whether to include zero or blank values in the publish.
This option suppresses rows containing all zeros or blanks. This can
speed up the process of publishing data substantially, depending on
the number of zero or blank cells.
Whether to prefix column names with the data type.
Select this option if you wish the column name to be prefixed with
the data type to avoid reserved name conflicts.
Chapter 12: Automating Tasks Using Macros
Whether to include these annotations in the publish.
Whether to include these annotations in the publish.
Whether to include attached documents in the publish.
Administration Guide 215

Chapter 12: Automating Tasks Using Macros
Parameter
Cubes to publish
Dimensions for publish
Select e.List items
e.List items to Publish
Job Monitoring
Timeout (in minutes)
Description
Publish - Incremental Publish
216 Contributor
Description
Whether to publish all or specific Contribution cubes.
Whether to use the default dimension for publish or specify a partic-
ular dimension.
Whether to publish all e.List items, use the selection from Contributor
Administration Console, or select individual e.List items.
A time period after which the macro step terminates if the job is not
completed. If the job does not succeed, an error appears. The default
is 1440 minutes.
A description for this reporting job.
Use this macro step to publish data so that only the e.List items that contain changed data are
published.If your publish selection contains more than one cube, but values change in only one
cube, the changed e.List items for all the cubes are republished. Before an incremental publish can
be run, the publish schema must be created, either by doing a full publish, selecting the cubes and
e.List items that you want to publish, or by generating and running publish scripts. When the Go
to Production process is run, publishes that are changes-only are suspended. Model changes that
result in changes to the publish schema may result in you needing to do a full publish of all the
selected cubes and e.List items.
Parameter
Macro Step Name
Where should the data be
published to?
Reporting Publish Container
e.List Item Filter
Job Monitoring
Description
The default name of this macro
Choose either to publish data to the default container or specify
an alternate publish container.
Select the check box if you wish to only published submitted e.List
items.

Delete Commentary
Parameter
Timeout (in minutes)
Description
A time period after which the macro step terminates if the job is
not completed. If the job does not succeed, an error appears. The
default is 1440 minutes.
Use this macro step to delete user or audit annotations and attached documents in a Contributor
application using date and time, character string, and filters for e.List item name.
Contributor applications can be annotated by users in the Web application. There are user and
audit annotations.
User annotations consist of comments per cell, cube (tab in the Web client), and model.
Audit annotations are records of user actions in the Web client, such as typing data, importing files,
and copying and pasting data. They can be enabled or disabled. For more information, see "Delete
Commentary" (p. 289).
When you delete commentary, the following process occurs:
❑ The macro step fetches and unpacks the model definition (this is a description of the entire
Contributor application).
❑ Processes the commentary for each e.List item in turn--deleting specified comments.
Tip: Adding a Wait for Any Jobs macro step before the Delete Commentary macro step ensures
that all jobs are complete before moving on to this macro step. For more information on the Wait
for Any Jobs macro step, see "Wait for Any Jobs" (p. 201).
The following table describes the relevant parameters.
Parameter
Macro Step Name
Application
Annotation Filters
Include user annotations in
the operation
Include audit annotations in
the operation
Description
The name of the macro step.
The name of the Contributor application datastore that the macro
step is being run against.
Chapter 12: Automating Tasks Using Macros
Whether user annotations are deleted. It is selected by default.
Whether records of user actions are deleted.
Administration Guide 217

Chapter 12: Automating Tasks Using Macros
Parameter
Apply date filter
Apply content filter
e.List items to process
Job Timeout (in minutes)
Execute an Admin Extension
218 Contributor
Description
Whether to delete commentary by a date filter.
If selected, you must enter the date and time before which all
annotations are deleted. This is the date when annotations were
created, not saved. Dates are in ISO8601 format.
Whether to delete commentary using a content filter. This is off by
default.
If selected, you must enter a character string as a filter.
Important: All commentary containing the character pattern spe-
cified are deleted. For example, if you specify the string pen,
annotations containing the words pencil and open are deleted.
You can specify which e.Lists to process.
The e.List item name is in the elistitemname column in the e.List
import file or e.List Item Id in Contributor Administration Console.
The names are case sensitive.
The following example contains a mixture of contributor e.List
items (A1 and A2) and a reviewer e.List item (B).
A1;A2;B
Alternatively, you can choose to process all e.List items.
A time period after which the macro step terminates if the job is
not completed. The default is 1440 minutes or one day.
Use this macro step to automate the running of the Generate Transformer Model extension.
To automate the Generate Transformer Model Extension, you must first run the extension using
Contributor Administration Console. This creates valid settings in the application datastore. The
macro then uses these settings.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Application
Admin Extension
Description
The name of the macro step.
The name of the Contributor application datastore that the macro step
is being run against.
The Admin Extension that you want to run.

Set an Application Online or Offline
Use this macro step to automate setting the Web application online or offline, preventing people
from accessing the Web site.
For more information about accessing the Web site, see "Working Offline" (p. 89).
The following table describes the relevant parameters.
Parameter
Macro Step Name
Application
Enable Web Client
Barrier
Description
Administrator Links (Macro Steps)
Execute Administration Link
The name of the macro step.
The name of the Contributor application datastore that the macro step
is being run against.
Whether to prevent users from accessing the Contributor application on
the Web. Clear the Enable Web Client Barrier option to bring the
application back online. Select this option to take the application offline.
Use this macro step to run an Administration Link automatically. Administration Links copy data
between Contributor applications in the same Planning Store without having to publish data first.
Note: You must first create a valid Administration Link for the application. For more information,
see "Administration Links" (p. 147).
Tip: Adding a Wait for Any Jobs macro step before and after the Execute Administration Link
macro step ensures that all jobs are complete before moving on to this macro step and after running
this macro step. For more information on the Wait for Any Jobs macro step, see "Wait for Any
Jobs" (p. 201).
The following table describes the relevant parameters.
Parameter
Macro Step Name
Administration Link
Job Timeout (in
minutes)
Validate Administration Links
Description
The name of the macro step.
The Administration Link to run.
A time period after which the macro step terminates if the job is not
completed. If the job does not succeed, an error appears. The default is
1440 minutes, or one day.
Chapter 12: Automating Tasks Using Macros
Use this macro step to validate an administration link automatically. Administration links copy
data between Contributor applications in the same Planning Store without having to publish data
Administration Guide 219

Chapter 12: Automating Tasks Using Macros
first. If you have an administration link based on an Analyst A-Table, you should validate the link
if a synchronize with Analyst has been done, or if there have been any changes to the A-Table in
Analyst.
Note: You must first create a valid administration link using an A-Table for the application. For
more information, see "Administration Links" (p. 147).
The following table describes the relevant parameters.
Parameter
Macro Step Name
Administration Link
Job Timeout (in
minutes)
Synchronize Administration Links
Description
The name of the macro step.
The administration link or links to run.
A time period after which the macro step terminates if the job is not
completed. If the job does not succeed, an error appears. The default is
1440 minutes, or one day.
Use this macro step to synchronize an administration link automatically. Administration links copy
data between Contributor applications in the same Planning Store without having to publish data
first. When you create an administration link based on an Analyst A-Table, there is always the
possibility that the underlying A-Table in Analyst can change over time. You can synchronize to
ensure the A-Table you have used in an administration link is up to date.
Note: You must first create a valid administration link using an A-Table for the application. For
more information, see "Administration Links" (p. 147).
The following table describes the relevant parameters.
Parameter
Macro Step Name
Administration Links
Job Timeout (in
minutes)
Macros (Macro Steps)
220 Contributor
Description
The name of the macro step.
The administration link or links to run.
A time period after which the macro step terminates if the job is not
completed. If the job does not succeed, an error appears. The default is
1440 minutes, or one day.
Macros are automated tasks such as those performed in Contributor Administration Console. You
can automate many macro-specific functions, such as running and importing macros.

Macro Doctor
Macro Test
Execute Macro
Use this macro step to generate a report on macros for debugging purposes. In the event of problems
with macros you may be asked by customer support to create and run the Macro Doctor macro.
The Macro Doctor captures information about the macros. It also allows you to see more detail
about the execution steps, and write them to files so that they can be inspected. Those macro step
definitions may be imported into another system, if required.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Folder for report and
Macro Steps (Enter Local
Application Server Path)
Include detailed progress for
Macro Steps
Description
The name of the macro step.
The location where the report and macro step information is created.
Whether to include detailed progress information for each macro
step. This extra information can often aid the debugging process.
Use this macro step to test if the macro components are running correctly. When successfully run,
it logs a user-specified Windows Application Event Log message that can be modified.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Message
Description
The name of the macro step.
A message to be logged.
Use this macro step to run another macro automatically. This macro step is very useful because
you can nest many macros inside one macro. For example, if you have weekly or monthly processes
that share macro steps, such as import and publish, you can use the Execute macro to run them
both.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Macro
Description
The name of the macro step.
The macro to run. Do not select the same macro that you are adding
this macro step to.
Chapter 12: Automating Tasks Using Macros
Administration Guide 221

Chapter 12: Automating Tasks Using Macros
Parameter
Number of times
Execute Command Line
Description
How many times the macro should run. The default is 1.
Use this macro step to run any program from the command line.
Important: Appropriate Access Rights need to be granted in order to use this macro step. For more
information, see "Access Rights for Macros" (p. 42).
The following table describes the relevant parameters.
Parameter
Macro Step Name
Command to Execute
Check for Return Code
Import Macros from Folder
222 Contributor
Description
The name of the macro step.
The Command to run.
One of the following:
● Ignore Return Code
ignores the return code from the program.
● Success Return Code
The macro step fails if the program returns any other code other
than the one specified. Typically, success is represented by zero.
Use this macro step to import a macro that has previously been exported.
Tip: It is possible to modify an exported macro step’s XML file with other editors and then import
again using this macro step.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Select Source folder
Process sub folders
Description
The name of the macro step.
The location of the macro to be imported.
One of the following:
● Only direct sub folders
● All sub folders

Parameter
Export Macros to Folder
How should duplicate
Description
One of the following:
names be handled ● Replace
● Append
● Create different name
Use this macro step to export a macro to a file location.
The following table describes the relevant parameters.
Parameter
Macro Step Name
Root folder (Enter Local
Application Server Path)
Manage Existing Files
Session (Macro Steps)
Remove Application Lock
Description
The name of the macro step.
The location where the macro is exported to.
One of the following:
● Archive
Use this to retain a history of your macros.
● Remove
● Leave
Use this macro step to remove an Application Lock. For more information, see "Managing Ses-
sions" (p. 61)
The following table describes the relevant parameters.
Parameter
Macro Step Name
Application
Description
The name of the macro step.
Chapter 12: Automating Tasks Using Macros
The name of the Contributor application that is locked.
Administration Guide 223

Chapter 12: Automating Tasks Using Macros
Running a Macro
224 Contributor
There are a number of scheduled and ad hoc methods that can be used to run the macro. You can
run a macro in the following ways.
● "Run a Macro from Administration Console" (p. 225)
● "Run a Macro from IBM Cognos Connection" (p. 225)
● "Run a Macro from an IBM Cognos 8 Event" (p. 226)
● "Run a Macro using Macro Executor" (p. 227)
● "Run a Macro using Command Line " (p. 228)
● "Run a Macro using Batch File" (p. 228)
For more information about the execution location and credentials for Contributor macros, see the
following table.
Type of Macro Execution
Administration Con-
sole
IBM Cognos Connec-
tion
IBM Cognos 8 Event
Macro Executor
command line
batch file
Execution Location
Planning Server with Dispatcher
Planning Service enabled
Planning Server with Dispatcher
Planning Service enabled
Planning Server with Dispatcher
Planning Service enabled
Local machine where the Macro
Executor is running. The machine
must have the Planning Server
installed.
Local machine where the command
line execution is running. The
machine must have the Planning
Server installed.
Local machine where the batch file
is running. The machine must have
the Planning Server installed.
Credentials
User logged on the Contributor
Administration Console
IBM Cognos Connection credentials
IBM Cognos Connection credentials
used to create event
Scheduler Credentials in the System
Settings of the Contributor Admin-
istration Console
Scheduler Credentials in the System
Settings of the Contributor Admin-
istration Console
Scheduler Credentials in the System
Settings of the Contributor Admin-
istration Console

Run a Macro from Administration Console
You can run a macro using the Macro tool in Administration Console.
Steps
1. In the Contributor Administration tree, click the Macros icon.
2. In the Macros list, select which macro you want to run and click Execute.
A dialog box appears informing you that the macro is running.
Tips: You can monitor the progress of the macro in the Macro Steps list. You can view any
error messages by clicking Error Details. You can stop a macro by clicking Stop. The macro
will stop before the next macro step begins.
Run a Macro from IBM Cognos Connection
Once published to IBM Cognos Connection, you can run the macro or create a job and use the
macro or job in an Event created in Event Studio.
You must first create a new macro or transfer an existing macro and publish it to IBM Cognos
Connection, see "Creating a Macro" (p. 194).
To secure access to Contributor macros in IBM Cognos Connection, see "Set Access Rights for
Contributor Macros in IBM Cognos Connection" (p. 43).
Steps
1. In IBM Cognos Connection, in the upper-right corner, click IBM Cognos Administration.
2. Click the Configuration tab and then click Content Administration.
3. Click Planning and then click Macros.
4. Set the general properties and permissions, see the IBM Cognos 8 Administration and Security
Guide.
5. To run the macro immediately or schedule it to run at a specified time, click Run with options
and select to run now or later. If you select later, choose a day and time to execute the
macro and click OK.
6. To create a recurring schedule to run the macro, click Schedule .
7. Under Frequency, select how often you want the schedule to run.
The Frequency section is dynamic and changes with your selection. Wait until the page is
updated before selecting the frequency.
8. Under Start, select the date and time when you want the schedule to start.
9. Under End, select when you want the schedule to end.
Tip: If you want to create the schedule but not apply it right away, select the Disable the
schedule check box. To later enable the schedule, clear the check box.
Chapter 12: Automating Tasks Using Macros
Administration Guide 225

Chapter 12: Automating Tasks Using Macros
10. Click OK.
The macro schedule is created and the macro runs at the next scheduled time.
Run a Macro from an IBM Cognos 8 Event
226 Contributor
You can create events that run Contributor macros when specified conditions are met. For example,
you can move data between applications using an Event Studio Agent to trigger a Contributor
macro that uses an administration link.
When you specify an event condition, you describe specific occurrences that an agent must detect
before it performs its tasks. The event condition is a query expression that you create using items
from the package.
Task execution rules specify when a task is performed. By default, a task is performed for new
instances of events and all ongoing instances of events, but you can change this.
You specify the task execution rules separately for each task in the agent.
For more information about creating an event and agent, see the IBM Cognos 8 Business Intelligence
Event Studio User Guide.
Steps
1. In Event Studio, click the Actions menu and then click Specify Event Condition .
2. Create a detail expression, a summary expression, or both by doing the following:
● If you want part of the event condition to apply to values of individual source items, click
the Detail tab and follow step 3.
● If you want part of the event condition to apply to aggregate values, click the Summary
tab and follow step 3.
3. In the Expression box, create a query expression by doing the following:
● Type text or drag items from the source tab.
● Type text or drag operators, summaries, and other mathematical functions from the func-
tions tab.
Tip: To see the meaning of an icon on the functions tab, click the icon and read the
description in the Information box.
4. If you want to check the event list to ensure that you specified the event condition correctly,
from the Actions menu, click Preview.
5. If you want to know how many event instances there are, from the Actions menu, click Count
Events.
6. From the File menu, click Save As .
7. Specify a name and location for the agent and click OK.
8. In the I want to area, click Add a task.

9. Click Advanced.
10. Click Run a planning macro task.
11. In the Select the planning macro dialog box, specify the task to include in the agent by searching
the folders to find the task you want and clicking the entry.
12. Under Run the planning macro task for the events, review the event status that will cause the
task to be run.
13. From the File menu, click Save .
If you want to add other events, see IBM Cognos 8 Business Intelligence Event Studio User
Guide.
14. In the I want to area, click Manage the task execution rules .
15. On the source tab , click one or more data items that uniquely define an event and drag
them to the Specify the event key box.
16. Click Next.
17. On the Select when to perform each task page, do the following:
● In the Tasks box, click the task that the agent will perform for the event statuses you specify.
● Under Perform the selected task for, select one or more event status values.
18. If you want to manage the execution rules for another task, repeat step 4.
19. Click Finish.
The execution rules for each task you selected are set.
Tip: If you want to reset the execution rules for every task in the agent to the default values,
from the Actions menu, click Remove Task Execution Rules. Each task is reset to be performed
for new instances of events and all ongoing instances of events.
20. Save the agent.
Run a Macro using Macro Executor
The Macro Step Plug-in
The Macro Executor is a program that takes the macro step and creates a component that performs
the action. After the component is created, the macro step is passed to it and then run.
MacroExecutor is typically installed to C:\Program Files\Cognos\C8\bin\epMacroExecutor.exe.
Note: Double-clicking epMacroExecutor.exe displays the available Command Line options.
Important: The Macro Executor must be installed on the computer you are trying to run it from.
You cannot execute it remotely.
Each macro step is associated with a macro step plug-in. In addition to running the specified func-
tionality, it validates the structure of the macro step.
Chapter 12: Automating Tasks Using Macros
Administration Guide 227

Chapter 12: Automating Tasks Using Macros
Run a Macro using Command Line
You can run the macro by typing the following from the command line, substituting the appropriate
macro name:
"C:\Program Files\Cognos\C8\bin\epMacroExecutor.exe" MacroName
Important: If the macro name has spaces in it, you must enclose it in quotes.
Run a Macro using Batch File
You can use Windows built in Scheduler (Control Panel, Scheduled Tasks).
Important: If jobs are scheduled to start while Go to Production is running for an application, the
job will fail.
The following is an example of a batch file (.bat) that can be used to run the macro:
"C:\Program Files\Cognos\C8\bin\epMacroExecutor.exe"
MacroName
IF ERRORLEVEL 1 GOTO ExceptionDetectedSettingUpLabel
IF ERRORLEVEL 2 GOTO ExceptionDetectedExecutingLabel
ECHO Succeeded
GOTO EndLabel
:ExceptionDetectedSettingUpLabel
ECHO Exception detected in setting up macro
GOTO EndLabel
:ExceptionDetectedExecutingLabel
ECHO Exception detected in executing macro
GOTO EndLabel
:EndLabel
PAUSE
Microsoft Calendar Control
Date Formats
228 Contributor
The Macros tool uses Microsoft Calendar Control to allow for date selections.
If you want to enable the use of the calendar graphic for date selection, this calendar control
(MSCAL.OCX) must be installed and registered on the computer on which Administration Console
runs. This control is available in the Microsoft Office suite or from Microsoft Visual Studio.
The format of dates used in the Macro step is as follows:
yyyy-mm-ddThh:nn:ss.ttt+00:00
It is in ISO8601 format, where:
Where:
● yyyy = year
● mm = month
● dd = date

● T (signifies time)
● hh = hour
● nn = minutes
● ss = seconds
● ttt = milliseconds
● +00:00=The time zone offset in hours and minutes, relative to GMT (Greenwich Mean Time)
also known as UTC - Coordinated Universal Time.
Here is an example:
2002-11-13T15:10:31.663+00:00
Troubleshooting Macros
You can monitor the status of macros within the Contributor Administration Console. If a macro
fails, the Error Details button is enabled. Click this button to display information about why the
macro failed. You can also find error messages in the error log.
Unable to Run Contributor Macros Using a Batch File
If you are running a Contributor macro using a batch file and it does not work, check the following:
❑ Can you run the macro using the Contributor Administration Console?
If not, check that the parameters are correct.
❑ Is the batch file syntax correct?
"C:\Program Files\Cognos\c8\bin\epMacroExecutor.exe" MacroName
Check that the correct filename is used in the actual macro step. If the file is open when the
batch command is run, the command fails and returns an error code of 1.
Check that the correct case is used for the macro name. The macro name is case sensitive.
Look in the TEMP folder of the Planning Service user context on the machine running the
Planning Service where the macro was executed. If you see the following message in the Error
Description column your security may not be set up correctly. For more information about
security, see "Security" (p. 29).
"Permission
denied"
Chapter 12: Automating Tasks Using Macros
Note: You can only run macros from the command line on a computer with a server install.
Administration Guide 229

Chapter 12: Automating Tasks Using Macros
230 Contributor

Chapter 13: Data Validations
Data validation is the process of aligning plans with targets by enforcing business rules and policies.
Use the data validation feature in IBM Cognos 8 Planning to define rules that ensure that incoming
data in a Contributor application is in the right format and conforms to existing business rules.
Building data validations involves defining a business rule that specifies the criteria that user input
must meet for the entry to be accepted.
A validation rule represents a single data entry requirement imposed on a range of cells in a single
cube of a model. This requirement is expressed as a rule or boolean formula (true or false) that
identifies invalid data entries when contributors or reviewers attempt to save or submit a plan. A
rule set is a collection of rules that can be associated with e.Lists and fail actions.
Data validation in IBM Cognos 8 Planning has the following benefits:
● You can apply different rules to different e.List items.
● It reduces the number of conditional IF-THEN-ELSE formula flags in an Analyst model.
● Centralizes data validation rules definitions.
Validation Methods
IBM Cognos 8 Planning provides these methods for validating data:
● presence check
Validates input into empty numeric or text cells. This method checks that critical data is present
and was not omitted from the plan. For example, contributors must enter forecast data for
product sales or provide an explanatory note for variances.
● dependencies
The text cell is based on values in other cells that contain single or compound conditions. For
example, contributors must enter an explanation into a text cell for any capital request that
exceeds $25,000 or for a capital request in the Other category greater than $25,000.
● business rule compliance
Ensures that the data entered conforms to the business rules. For example, the pay range for
new hires must not exceed top of pay scale.
● single numeric validations, with variation by e.List item
For example, all Division A profit centers must have a forecast profit margin that is equal to
or exceeds 20% and a profit that exceeds $250,000. All Division B profit centers must have a
forecast profit margin that is equal to or exceeds 15% and a profit that exceeds $0.
Validation Triggers
Validation rules are run on the Contributor Web client or on Contributor for Excel. A rule is
evaluated under one or more of the following conditions:
Administration Guide 231

Chapter 13: Data Validations
● automatically, when a contributor saves a plan or when a reviewer submits a plan
● manually, when a contributor or reviewer selects the Validate Data option from the File menu
or the Validation Data toolbar button in the Web client
● manually, when a contributor or reviewer selects the Validate Data option from the Contributor
menu in Excel
When one of these triggers occurs, the rule formula is evaluated to either pass or fail. If any of the
rules in the rule set detects a failure during the evaluation, the rule set is considered to have failed
and the fail action specified in the rule set is performed. The contributor or reviewer may be prevented
from saving or submitting the plan.
Setting Up Data Validation
232 Contributor
You administer and maintain data validation in the Contributor Administration Console. The Data
Validations branch under the Applications node includes specific components that are required at
each stage of the data validation workflow.
Important: Rules that were built prior in versions to IBM Cognos Planning 8.2 are incompatible
with the current product version, and must be redefined as follows.
The process flow for defining validations as follows:
❑ Plan how the rule applies to a reviewer, contributor, or both a reviewer and contributor (p. 233)
For reviewers, define validation rules against post-aggregate D-Lists. Because reviewers are
managing the aggregate of their contributors, the post-aggregate calculations, which are results
from all e.List items, are applicable only to the reviewer.
For contributors, define validation rules against pre-aggregation D-Lists (before the e.List).
For contributors and reviewers, define validation rules against post-aggregate calculations.
❑ Synchronize the Contributor applications with the Analyst models
Ensure that all cubes in an application are updated when the underlying objects in Analyst
change. Changes to the model may include renaming dimensions or adding, deleting, or
renaming dimension items. By synchronizing, you can import from Analyst the updated cube
definition in the application.
❑ Define one or more rules (p. 237)
In the Data Validations, Rules folder, use the Validation Rule wizard to define the validation
rules. Specify the rule message that appears when a data fails validation. Contributors or
reviewers can then react to the failed entry. The D-Cube to which the validation applies, the
measures dimension whose items are used to define the rule formula, and the scope or target
range for validation.
❑ Define one or more rule sets (p. 239)
After you create a rule set, you must add at least one rule to the rule set.
In the Data Validations, Rule Sets folder, you can create rule sets by adding one or more rules,
and assigning fail actions. A rule set applies to a single data validation process.

❑ Associate the rule sets with groups of e.List items (p. 240)
In the Data Validations, Rule Set e.List Items folder, associate the rules sets with the groups of
e.list items. Specify the roles, such as contributors, reviewers, or contributors and reviewers
and their subordinates, to which the rule set applies.
❑ Run the Go to Production process
Perform this process to make the application, including its new business rules and data format
constraints, available to users on the Web client and Contributor for Excel.
The Impact of Aggregation on Validation Rules
Before creating a validation rule, it is important to understand how the aggregation of totals works
for a Contributor application. For Contributor models, data is stored according to the e.List item.
For a contributor, only one e.List item exists. That means calculations that occur after the e.List
item must include only their own e.List item.
For a reviewer, the data is an aggregation of all the e.List items that roll up into that reviewer.
Therefore, the model may contain sums of the values for the e.List items (pre-aggregation), and
other calculations that are based on the sum of the values after the e.List items are aggregated (post-
aggregation).
Because an e.List item for a reviewer is an aggregation of multiple e.Lists, the calculations that
appear in the D-Lists after the e.List dimension must include data from all the e.List items that roll
up into the e.List item for that reviewer. These calculations change when the lower-level e.List items
save data. We recommend aggregating the values of the calculations before the e.List dimension
(pre-aggregation calculations) because the post-aggregation calculations are recalculated when data
changes for one of the e.List items that is aggregated. The reason is that the pre-aggregation calcu-
lations belong within a single e.List item and the data from other e.List items does not affect the
calculation result.
Example - In Analyst, Setting Up the D-Cube
To use pre-aggregation calculations for a dimension, you must ensure that the order of the dimension
list in a D-Cube is correct. When a planner sets up a D-Cube, D-Lists are chosen in the order that
uses the calculation D-List first and the aggregation D-Lists last.
In the following example, the first dimension, RollupTest Slots, holds data values. The second
dimension, RollupTest FirstDim, occurs prior to the e.List item, so its calculations are pre-aggreg-
ation. The next dimension is the e.List. The final dimension, RollupTest LastDim, is post-aggregation
because it occurs after the e.List.
Chapter 13: Data Validations
Administration Guide 233

Chapter 13: Data Validations
234 Contributor
As shown next, the RollupTest FirstDim D-List includes the Conditional item, which is a test for
data input greater than 50,000, with a default calculation option of Force to Zero for the Flag
Value. That means it will not calculate a value for this aggregate.
The next example shows the RollupTest LastDim D-List that includes Conditional1 items that test
for LinkedValue greater than 50,000.

The following graphic shows the RollupTest LastDim D-List that includes Conditional2 items that
test for InputValue greater than 50,000.
The D-Cube that is built with RollupTest FirstDim and RollupTest LastDim shows how the values
for cells are calculated.
Chapter 13: Data Validations
Administration Guide 235

Chapter 13: Data Validations
236 Contributor
When the underlying calculations are defined in Analyst, you can view the outcome in the Contrib-
utor Web client. Suppose that in the Contributor Web client, there are three e.List items, A1 Profit-
center, rolls up into A Region and A2 Profit-center.
For A1 Profit-center, because the pre-aggregate test is based on conditional values of 50,000, only
input cell passes the test. The Conditional cell test against the Input Value item, so the Conditional
is 0 and 1. Conditional1 tests LinkedValue and Conditional2 tests InputValue. The post-aggregate
is Text1 and Text2.
For A2 Profit-center, you can see how the pre-aggregation (LinkedValue and InputValue) and post-
aggregation (Text1 and Text2) tests change.
The Reviewer e.List item shows that the Flag Value is not present. The Force to Zero option in
Analyst suppressed this from the reviewer e.List item because no data was present.
The Conditional values are sums of the values from the Contributor e.List items. For A1 Profit-
center, the two values are 0 and 1. For A2 Profit-center, the values are 1 and 1. The aggregation
added the values of these flags for a reviewer of 1 and 2.
Contitional1 and Conditional2 do not have their values added because the calculation is recalculated
against the aggregation total. Note that the Conditional1 value shows the test failing in the first
row for the reviewer. Text1 and Text2 reveal that the formatted D-List items appear based on the
recalculated Conditional1 and Conditional2 fields.

Define a Validation Rule
To support your business decisions, your contributors must enter data that is valid and accurate.
Validation rules give you a simple way to build business logic that checks the validity of data before
a plan is saved or submitted.
Rules also include an error message that appears when the rule returns a value of false. The text
strings in error messages, names of the validation rules, and rule set names, can be translated through
the Translation node in the Development branch in the Administration Console. Use the Content
Language tab, which handles the translation of model strings, to specify your settings. Use the
Product Language tab to translate all fixed parts of the validations, such as the following message:
Submit is not allowed due to one or more blocking validation errors
When creating a rule, you must also specify the cell range (scope) that is subject to validation.
A validation rule contains a formula or expression that evaluates the data in one or more cells in
the grid and returns a value of true or false. If you require complex expressions that are cross-
dimensional or deeply nested, we recommend that you first construct them in IBM Cognos 8 Planning
- Analyst.
● Do not create contradicting rules for the same target range because they will prevent contributors
or reviewers from saving the plan.
● If an entry does not conform to a rule, ensure that you provide explicit instructions in your
message. For example, instead of stating invalid entry, state the message as Capital costs
greater than $25,000 must be pre-approved.
● Consider which items are visible and editable for the contributor. Cells that are readable can
cause a validation error, but hidden or no data cells do not impact validation rules and cannot
cause a validation error.
You can use saved selections to specify the data that you want validated. You can name and save
a collection of items from a dimension using the Access Tables and Selections node under the
Development branch in the Administration Console. Saved selections are dynamic in that the items
in the selection change when an application is synchronized following changes to the Analyst model.
Hidden, and empty cells are not validated when the rule set is run.
Steps
1. Open the Administration Console.
2. In the Administration tree, expand Datastores, DatastoreServerName, Applications, Applica-
tionName, Development, and the Data Validations folder.
3. Click the Rules folder.
Chapter 13: Data Validations
Administration Guide 237

Chapter 13: Data Validations
238 Contributor
4. Click New.
The New Validation Rule wizard appears.
5. On the Welcome page, click Next.
6. On the Validation Rule Options page, do the following:
● In the Rule Name box, type a unique name that distinguishes the validation rule from
others.
No blanks or special characters, such as apostrophe (’), colon (:), question marks (?), and
quotation marks (") are allowed.
● In the Rule Message box, type the error text message that you want the contributor or
reviewer to see if the validation fails.
We recommend that a message is included in the rule to facilitate data entry. The message
should contain meaningful information that helps the contributor or reviewer enter the
correct data.
7. Click Next.
8. On the Validation Rule Cubes page, select the D-Cube against which the rule is applied, and
click Next.
Assumptions cubes do not appear in the list of available D-Cubes.
9. On the Validation Rule Dimension Selection page, select a measures dimension in the D-Cube
whose items are used to create the boolean formula for the rule, and click Next.
A rule expression is defined against a specific dimension in the selected D-Cube. All dimensions
of the cube, except the e.List, are listed.
10. On the Validation Rule Expression page, build the business logic by defining a rule formula
that evaluates to either true or false, and click Next.
11. Under Available components select items from the specified dimension in the D-Cube that you
want to use to define your rule expression and then click the arrow to move them to the
Expression definition box. Use the IF statement, AND/OR boolean operators, or logical
comparison operators, such as =, , and = 0.15) AND (Margin

All dimensions in the selected D-Cube are available with the exception of the measures and
e.List dimensions. Note that because the item includes aggregates as well as details, it
is not an optimal data item to include in a rule.
13. Click Finish. If you want to change or review your settings, click Back.
The rule is automatically saved and associated with the model. It is now available for inclusion in
a rule set.
Define or Edit a Rule Set
You can add rules to rule sets. Each rule set is associated with an action that occurs if the data entry
fails validation. You can use more than one rule set for each validation process on a cube, with
multiple fail actions or messages.
You must create one or more rules before you can define a rule set.
Steps
1. Open the Administration Console.
2. In the Administration tree, expand Datastores, DatastoreServerName, Applications, Applica-
tionName, Development, and the Data Validations folder.
3. Click the Rule Sets folder, and choose whether to create a new rule set or edit an existing one:
● To create a new rule set, click New.
● To edit an existing rule set, click the rule set that you want to change, and then click Edit.
4. In the Rule Set Name box, type a unique name for the rule set that distinguishes it from the
others.
5. In the Fail Action box, specify one of the following types of action to be triggered when one
or more rules in the rule set fails validation:
● To show only the rule message and take no action, click Message Only.
● To show the rule message and restrict contributors or reviewers from submitting the plan,
click Restrict Submit.
● To show the rule message and prevent contributors or reviewers from either saving or
submitting the plan, click Restrict Save and Submit.
Important: Use caution when applying this setting - this is not considered a best practice. If one
or more rules fail, contributors or reviewers cannot save the plan. To close the plan, the rules
must be resolved to a value of true, which may not be possible for the user to achieve.
6. In the upper rule grid, select the rule or rules that you want to include in the rule set, and click
Add.
The selected rule or rules appears in the lower grid.
Tip. You can remove a rule from the rule set using the Remove button.
7. Click OK.
Chapter 13: Data Validations
Administration Guide 239

Chapter 13: Data Validations
Edit a Validation Rule
8. Click the Save button to save the rule set.
You can now associate the rule set to e.List items (p. 240).
You can modify a rule to better reflect the constraints placed on data entry for a particular D-Cube.
Steps
1. Open the Administration Console.
2. In the Administration tree, expand Datastores, DatastoreServerName, Applications, Applica-
tionName , Development, and the Data Validations folder.
3. Click the Rules folder.
4. Select a rule that you want to change, and click Edit.
5. Choose how you want to modify the rule, and click OK.
6. If you want to rename the rule to something more obvious, in the Name box, type the new
name.
7. If you want to change the message to reflect the new constraints or limitations, in the Message
box, type the new message.
8. If the constraint on data entry changed, do the following:
● Click the ellipses button next to the Expression box.
● In the Edit Validation Rule Expression dialog box, define the new boolean expression used
to evaluate data entry and click OK.
● Under Available components, select items from the specified dimension in the D-Cube that
you want to use to define your rule expression, and then click the arrow to move them to
the Expression definition box. Use the IF statement, AND/OR boolean operators, or logical
comparison operators, such as =, , and

2. In the Administration tree, expand Datastores, DatastoreServerName, Applications, Applica-
tionName ,Development, and the Data Validations folder.
3. Click the Rule Set e.List Items folder.
The Validation Rule Set grid shows all the available rules sets.
4. Associate a rule set to an e.List item as follows:
● Under Validation Rule Set, click a rule set.
Tip: Press Ctrl + click to select multiple rule sets.
● Under E.List Item Name, click the e.List item to which you want to apply the rules, and
click Add. You can also select ALL, All DETAIL, ALL AGGREGATE, or any e.List saved
selections.
The By Rule Set tab is filtered by rule sets and is sorted by all the rules sets and their asso-
ciated e.List items. The By e.List Item tab is filtered by e.List items that are associated with
the current rule sets.
5. Click the Save button to save the associations to the e.List.
Chapter 13: Data Validations
Administration Guide 241

Chapter 13: Data Validations
242 Contributor

Chapter 14: The Go to Production Process
Use Go to Production to formally commit a set of changes. Any issues such as invalid editors, an
invalid e.List, and destructive model changes, are reported by the Go to Production process.
The Go to Production process can be automated (p. 202) so that you can schedule it to run during
slow periods.
Go to production consists of the following stages:
● pre-production
● go to production
● post-production
The crucial stage is the go to production stage where the old production application is replaced by
the incoming development application.
Until the go to production stage, all Web client users can use the old production application as
normal. Immediately after the go to production stage, a new production application exists that Web
client users then use. After the go to production stage, Web client users attempting to open a model
have access only to the new production application. However, if users are already viewing or editing
a model from the old production application at the time of the go to production stage, client-side
reconciliation is required.
In the go to production stage, the old production model definition is replaced by a new production
model definition (the incoming development model definition). Many development changes have
no effect on the structure or content of production data blocks and affect only the production model
definitions. An example is everything appearing within the Web-Client Configuration branch in
the Contributor Administration Console. If these are the only changes made, the production
application is fully updated when the go to production stage is complete.
Other development changes require a new production model definition and require the production
data blocks to be updated. For example, synchronizing with the Analyst model can change the
structure and content of data blocks in many ways. If changes that effect data blocks have been
made, the go to production stage fully updates the production model definitions as normal, but the
data blocks are updated by a subsequent reconciliation process.
If an import is performed, an Analyst to Contributor D-Link is run, or if an administration link is
run in the development application, then import data blocks are created. If there are import data
blocks at the point of the go to production stage, these import data blocks are moved into the new
production application. After the go to production stage, the import data blocks are combined with
the production data blocks, which are also handled by the reconciliation process. After this, the
import data blocks are removed from the development application.
In summary, the go to production stage replaces the old production model definition with a new
one, and moves any import data blocks into production. If import data blocks or changes that affect
production data blocks are made, the production data blocks are updated by a reconciliation process
that follows Go to Production.
Administration Guide 243

Chapter 14: The Go to Production Process
During the go to production stage the application is taken offline temporarily to ensure data
integrity. The new e.List item workflow states are determined to correctly process any e.List hierarchy
changes. As soon as those changes are applied the application goes online again and the post-pro-
duction processes are started. This offline period is typically so short that it is transparent to users,
but it can sometimes exceed one minute.
Planning Packages
244 Contributor
In IBM Cognos 8, a package is a folder in IBM Cognos Connection. You can open the package in
a studio to view its content. A Planning package is a light-weight package that contains only the
connection information to the cubes in the Planning application. The D-list and D-List item metadata
are extracted from the Planning application at run-time.
To access Contributor applications, you must select the option to create the package when you run
Go to Production. This option also gives users access to IBM Cognos 8 studios from the Contributor
application if they have the studios installed and enables users to report against live Contributor
data using the Planning Data Service (p. 302).
You may choose not to create a package if you just want to publish the data and create a PowerCube
or an Framework Manager model using the extensions. This will save time because the Go to Pro-
duction will finish more quickly.
To create a Planning Package, you must have the Directory capability. This is not part of the Planning
Rights Administrator role, but it is part of the Security Administrator role. For more information,
see "Capabilities Needed to Create IBM Cognos 8 Planning Packages" (p. 34).
The Planning Package is created with the same display name as the Contributor application by
default, and a data source connection named IBM Cognos 8 Planning - Contributor is created in
Framework Manager. You can configure the name of the Planning Package, and add a screen tip
and description. For more information, see "Set Go to Production Options" (p. 82).
The security on the Planning Package is as follows:
● All users, groups, or roles that have Planning Administration capability are granted adminis-
trative access to the package.
● All the users who have access to the application are added as user of this package.
● The user who is logged on to the console when performing the Go to Production is the user
who creates the package. Therefore, that user is given administrative access to the package.
This user is not necessarily a planning administrator because they could have been granted only
Go to Production permission by a planning administrator.
If you remove an application from the console, any corresponding planning package in IBM Cognos
Connection is disabled. The package will be hidden from the users and will appear with a locked
icon to administrators. This allows administrators to maintain an application while making it appear
offline to users. When the application is re-added in the console, the corresponding planning
package is re-enabled.

Reconciliation
The reconciliation process ensures that the copy of the application used by the on the Web is up to
date. For example, all data is imported, new cubes are added, and changed cubes are updated. For
more information, see "Reconciliation" (p. 54).
The first time Go to Production is run for an application, all e.List items are reconciled. Subsequently,
only some changes result in e.List items result in changes being made. Reconciliation can take some
time, depending on the size of the e.List. If you are making changes that require reconciliation,
check that you made all required changes before running Go to Production.
The Production Application
Model Definition
Data Block
When you first create a Contributor application, there is only a development version. The production
version is created only after Go to Production is run. The production version of the application is
the version that users see in the web. Changes made in the development application apply only after
Go to Production is run.
The production version of a Contributor application consists of one or more model definitions,
and one data block for each contribution or review e.List item.
Before you can run Go to Production, the Contributor application must contain at least an e.List.
If you can run the Go to Production process without setting any rights, no one can view the
application on the Web. You can preview the application prior to setting any rights by selecting
Production, Preview in the Administration Console.
When you start Go to Production, job status is checked. If jobs are running or queued, you cannot
run Go to Production. A message appears prompting you to go to the Job Management window.
For more information, see "Managing Jobs" (p. 52).
If there are discrepancies in information about translations in the datastore table and the model
XML, you cannot run Go to Production. For more information, see "Datastore Options" (p. 84).
A model definition is a self-contained definition of the model. It holds definitions of the dimensions,
cubes, and D-Links of the model, as set up in IBM Cognos 8 Planning - Analyst. It also holds details
of modifications applied in the Contributor Administration Console. This includes configuration
details, such as navigation order for cubes, options such as whether reviewer edit or slice and dice
are allowed, and Planning Instructions. A model definition also includes e.List details and access
table definitions. It also contains all assumptions cube data, because this does not vary by e.List
item.
Chapter 14: The Go to Production Process
The data block for an e.List item contains all data relevant to an individual e.List item, except
assumptions cube data (p. 119). It contains one element of data for every cell in the model, except
for any cell identified as No Data by Contributor access tables (p. 122). No Data cells are generally
treated as if they did not exist. This reduces the volume of data that must be downloaded to and
uploaded from clients, speeding up client-side recalculation and server-side aggregation.
Administration Guide 245

Chapter 14: The Go to Production Process
Production Tasks
When a Web client user opens an e.List item by clicking its name in the status table, a model
definition is opened, and then the appropriate data block is loaded into it. If a multi e.List item
view is opened, more than one data block is loaded. Wherever possible, the model definition and
data block are loaded from the client-side cache if enabled. If the client-side cache does not contain
an up-to-date version of the model definition or the data block, they are downloaded from the
server. Note that data in the data block is not compressed, although compression and decompression
takes place on transmission to and from the client.
In addition to a data block, each e.List item also has an annotation block. Various translation tables
exist if multiple languages are used.
You can do the following to the production version of a Contributor application:
● publish data
You publish the production version of the application. However, you must set dimensions for
publish in the development application and then run Go to Production to apply the changes to
the production version. This is because setting dimensions for publish requires datastore tables
to be restructured (p. 82).
● delete user and audit annotations
● preview the workflow state
● preview the model and data
● configure extensions for the Classic Contributor Web Client
Extensions allow you to extend the functionality of the Classic Contributor Web Client in ways
that fulfill business requirements. The Contributor Web Client includes the Get Data and Export
for Excel functionary.
● run administration links
Cut-down Models and Multiple Languages
246 Contributor
If neither cut-down models nor multiple languages are used, there is just one master model definition
for an application.
When cut-down models are used, separate model definitions are produced for individual e.List
items or groups of e.List items, according to the cut-down model option chosen (p. 249).
When multiple languages are used, a separate master model definition exists for each language.
Each master model definition contains just the relevant translated strings to prevent the master
model definition from becoming excessively large.
An application may use multiple languages and cut-down models.

The Development Application
Web client users interact only with the production version of an application. Most application
configuration or administration is performed in the development version of an application. This
has no impact on the production application or the web client users, until you run Go to Production.
In considering the Go to Production process, the following components are relevant:
● The development version of the master model definition
● A set of import data blocks
Development Model Definition
Import Data Blocks
With the exception of data import, any configuration performed in the development application
affects the development model definition. In the Contributor Administration Console, changes are
implemented to the development model definition as soon as they are saved. For example, new
access table definitions are stored in the development model definition when you click the save
button in the main Access Tables window.
You cannot undo individual changes made to the development application. However, you can reset
the entire development application which then matches the current production application, using
the Reset Development to Production toolbar button .
The final stage of the Contributor import process creates a set of import data blocks. The Prepare
import stage extracts data from the import staging tables and creates one import data block for
each contribution e.List item with import data. Import data blocks contain data for only one e.List
item, and contain only valid data. Invalid data, such as data that does not match any dimension
item or targets formula items or No Data cells, is written to an import errors table (ie_cubename).
No import data block is created for e.List items with no import data.
By removing all irrelevant or invalid data, the import data block for an e.List item is kept as small
as possible. This is crucial for the subsequent reconciliation process, particularly for client-side
reconciliation.
Note that if you use the Prepare zero data option, an empty import data block is created for all
e.List items.
Because the Prepare process is performed using the job architecture (a Prepare_Import job), it can
be scaled out, and monitored in the normal way. It does not conflict with other jobs for the
application, but it is not possible to run the Go to Production until it is complete.
Analyst to Contributor D-Links and administration links that target the development application
also create import data blocks that are brought into the production application by the Go to Pro-
duction process. Data from links that target the production application is brought in to the applic-
ation by an activate process that triggers a reconcile job. For more information see "Reconcili-
ation" (p. 54).
Chapter 14: The Go to Production Process
Administration Guide 247

Chapter 14: The Go to Production Process
Run Go to Production
You must run Go to Production to commit any changes made to the development application, such
as configuration options, importing data, and synchronize with Analyst.
You must wait for all jobs to stop running before running Go to Production. This includes the
reconcile job.
Before running Go to Production, ensure that
● an e.List, was imported, rights were set
● appropriate data dimensions for publish were set
● the Copy Development e.List item publish setting to production application and Prevent client-
Steps
side reconciliation options are set as required
For information about these options see "Go to Production Options Window" (p. 248).
1. Select the Contributor application.
2. Click the Go to Production button. If this button is not enabled, check that the application has
an e.List. If so, you do not have access rights to run Go to Production .
Go to Production Options Window
Back-up Datastore
Use the Go to Production Options window to specify whether to back up the datastore (recommen-
ded), whether to reset the Workflow State, and whether to show information about invalid owners
and editors. The Invalid owners and editors option is not relevant the first time you run Go to
Production.
This option creates a backup of the development and production application and stores them in
the location specified during application creation or in the Datastore Maintenance window (p. 84).
We recommend that you set this option. If you clear this option, a warning advises you to make a
backup in case of problems. Note that when you automate the Go to Production process, there is
no backup option and you should schedule a backup to be made before running the Go to Production
process.
Create Planning Package
248 Contributor
In order to be able to access Contributor applications from IBM Cognos Connection, you must
select this option when you run Go to Production. This option also gives users access to IBM
Cognos 8 studios from the Contributor application if they have the studios installed, and enables
users to report against live Contributor data using the Planning Data Service (p. 302). For more
information, see "Planning Packages" (p. 244).

Display Invalid Owners and Editors
Workflow States
Use this option to choose whether to show owners and editors who become invalid when you run
Go to Production. This option can add some time to the Go to production process.
Reset resets the state of the e.List items in the Contributor Application.
If required, select one of the following options:
● Not Started
This sets every e.List item back to the state of Not Started.
● Not Started and Work in Progress
This sets all e.List items that are not in a state of Not Started to the state of Work in Progress.
e.List items that are Not Started remain in this state. This option aggregates all data but does
not indicate whether e.List items were modified.
● Work in Progress
this sets all e.List items to a state of Work in Progress, meaning that changes were saved but
not submitted.
● Locked
this locks all e.List items. No changes can be made to locked e.List items, but the data can be
viewed.
Show Changes Window
Skip top e.List items enables you to reset all but the top e.List items.
The Show Changes window contains tabs which shows the differences between the development
application that you are running the Go to Production process on and the current production
application. By looking at this information, you can see the effect that Go to Production has on the
production application.
The First Time Go to Production is Run on an Application
The first time you run Go to Production, no changes are shown. If you imported data, a tab shows
import data details (p. 254). You can cancel the Go to Production process at this stage.
After you view Import data details, click Next.
If you have set cut-down model options (p. 74) the cut-down models job monitor is shown until
the cut-down models job has finished running. You can cancel while the cut-down models job is
running, but not after it is complete. The final process is started automatically.
Subsequent Go to Productions
When you run Go to Production more than once, depending on the changes you have made, you
may see the following information:
● model changes
Chapter 14: The Go to Production Process
Administration Guide 249

Chapter 14: The Go to Production Process
● import data details (p. 254)
● invalid owners and editors (p. 254)
● e.List items to be reconciled (p. 256)
Model Changes Window
Changes to Cubes
250 Contributor
The model changes window shows the changes made to the IBM Cognos 8 Planning - Analyst model
since the previous Production application was created.
For example, which cubes were added, removed, or had their dimensions changed, and whether
dimensions were added, deleted, or substituted.
Pay particular attention to changes that could affect production data, such as cubes or dimension
items deleted.
Click Advanced to view a detailed description of the differences between the previous Analyst model
and the current model. It lists the cubes and dimensions that changed. When you click an item, a
breakdown of the changes appears. Typically, this information is used for debugging purposes.
When you expand the cubes listed under Common Cubes, the following branches are listed under
each cube: New, Old and Differences.
New and Old contain the same categories of information and list what was in the old model and
what is in the new model.
Name
Dimensions
AccessTables
AccessLevel
BaseFormat
Description
The dimensions in the order in which they were in Analyst.
The access tables assigned to the cube.
The base access level for the cube.
The D-Cube format as defined in Analyst. If no format is defined,
it defaults to the system default.

Name
UpdateLinks
BreakBackEnabled
MeasuresDimension
AggregationDimension
Description
The update links that are associated with the cube.
1= breakback enabled for the cube.
-1= breakback disabled for the cube.
-1 = no dimension for publish set on the cube.
n = the position in the dimension order in Analyst of the dimension
for publish, excluding the e.List.
1 = the cube has an e.List.
-1 = no e.List.
The following window shows the differences for the D-Cube Revenue Plan that result from adding
a dimension:
Name
[New] Dimensions
[Old] Dimensions
[New] AggregationDimen-
sion
[Old] AggregationDimen-
sion.
Description
Lists the dimensions after the synchronize.
The dimensions before the synchronize.
Chapter 14: The Go to Production Process
A positive number indicates that this cube contains the e.List.
-1 indicates that there was no e.List in this cube in the old model.
Administration Guide 251

Chapter 14: The Go to Production Process
Changes to Dimensions
Changes to Links
252 Contributor
When a dimension is changed, three branches are listed under each dimension: New, Old, and
Differences. When you click one of these branches, something similar to the following appears:
This table lists the following details for each dimension item in the Now, Old, and Differences
windows.
Name
Item Guid
Item Id
Name
Parent Index
Description
A unique internal reference for items in a model. When you add a dimension
item, this item is assigned a GUID.
Internal unique numeric reference.
The name of the dimension item.
Internal reference that indicates the parent of each item in the hierarchy.
When a link changes, three branches are shown, New, Old, and Differences.

The New and Old branches show the following information.
Name
Source
Target
Correspondences
Mode
Scale
UseRounding
RoundingDigit
Match names: Link name
SourceDimension
Description
The name of the source D-Cube.
The name of the target D-Cube.
The matched dimensions if any exist.
The execution mode selected for the link.
The scaling factor applied to the D-Link.
The rounding factor used.
The rounding digit used.
The matched dimensions.
The source dimension.
Chapter 14: The Go to Production Process
Administration Guide 253

Chapter 14: The Go to Production Process
Name
SourceSubColumns
TargetSubColumns
CaseSensitive
TargetCalculations
DumpItem
Selection:Dimension name
Selection
IsTarget
Description
The source sub column, if it exists.
The target sub column, if it exists.
1 = on
0 = off
The target calculation, if it exists.
Indicates that data from unmatched source items is assigned to a
dump item in the target D-List.
The dimension name where there is no match.
The selection of items.
Indicates the target.
0 indicates a selection on the source dimension rather than the tar-
get.
When you click the Difference branch, you see an overview of the changes.
Import Data Details Tab
The Import data details tab appears only if you imported data. This window shows the e.List items
that have import data blocks prepared. Within each e.List item, the number of data cells prepared
per cube are listed.
Invalid Owners and Editors Tab
Invalid Editors
254 Contributor
Invalid owners and Editors tab appears only if you have selected the Display invalid owners and
editors check box in the Go to Production Options tab.
This tab lists users who are currently editing or annotating, and who will become invalid when the
development application becomes the production application.
The Editor column lists the editors who are currently editing the e.List item.
An invalid editor is a user who was editing or annotating an e.List item when Go to Production
was run, and, due to a change, can no longer edit or annotate the e.List item. These changes can
be one of the following:
● The e.List item that was being edited or annotated was deleted.
● The rights of a user were changed to view.

Editor Lagging
● Reviewer edit (p. 74) is prevented.
● The review depths of an e.List item that is being edited by a reviewer or annotated were changed
so that the user no longer has access.
Editor lagging lists those Web client users who are editing at the time, either on or offline.
Steps
1. Go to the Production branch of the application, and then click Preview.
2. Right-click on the e.List item and select Properties.
3. Click the Editors tab.
If the e.List item is being worked on off-line, a cross is shown next to Edit session connected.
This is shown because in some circumstances, a user is unable to save their changes. For example,
a reconcile job runs for the e.List item that is being edited or annotated and client side recon-
ciliation is prevented. The user is bounced off the e.List item, losing any changes. They can save
the contents of the grid locally to a text file, and re-import the file. Another example is when
two reconcile jobs run for the e.List item while someone is editing or annotating it (on or offline).
The Prevent client side reconciliation option can be on or off. The user is bounced off the e.List
item, losing any changes, or is unable to bring the data online.
Note that an administration link or an Analyst to Contributor link to a production version of
an application causes a reconcile job to be run to update the e.List items.
Sometimes the Administration Console cannot detect whether a user is still editing or annotating,
although the Administration Console is always aware of the start of an editing session. An
editing session is ended when the user closes the grid, and submits the e.List item. Normally
these actions are detected by the Administration Console. However, if the user loses their net-
work connection while editing, the Administration Console thinks that the user is still editing.
If the user reconnects to the network and ends the session by closing the grid or submitting the
e.List item, the Administration Console detects that the edit session is ended.
How a User Can Lose Access to an e.List Item
The following changes result in an end user losing access to an e.List item they are currently editing
or annotating:
● A user who was editing or annotating an e.List item when Go to Production was run was
deleted.
● An e.List item that was being edited or annotated when Go to Production was run was deleted.
● The rights of a user who was editing or annotating an e.List item when Go to Production was
run have been changed to View.
● Reviewer edit was prevented and the reviewer was editing an e.List item when Go to Production
was run.
Chapter 14: The Go to Production Process
Administration Guide 255

Chapter 14: The Go to Production Process
● The review depths of an e.List item that is being edited by a reviewer (with reviewer edit allowed)
or annotated have been changed so that the user no longer has access.
● A reconcile job (p. 54) is run for the e.List item that is being edited or annotated and Client
side reconciliation is prevented.
● Two reconcile jobs have been run for the e.List item while someone is editing or annotating it
(on or offline). Prevent client side reconciliation can be on or off. Note that running an
administration link or a AnalystContributor link causes a reconcile job to run.
● Another user takes ownership of the e.List item while the current user is editing it or annotating.
● Users will receive a warning message and the buttons in the grid will disappear. Users will be
able to right-click in the data and save to file.
e.List Items to be Reconciled Tab
The Owner column lists the current owners of the e.List items to be reconciled. By default, the
current owner is the first person in the Rights table to be assigned to the e.List item with rights
higher than View. If another owner takes ownership of the e.List item, they become the current
owner (p. 95). If the e.List item has no current owner, it shows System.
The Editor column lists the names of users who are currently editing or annotating the e.List item
to be reconciled. If the e.List item is currently being edited, this is the same name as in the Owner
column. If the e.List item is not being edited, the cell says No Editor.
The Import Data Block column indicates whether there are import data blocks for the e.List item.
Cut-down Models Window
Finish Window
256 Contributor
If cut-down models (p. 138) are required, they are generated at this stage so that they are available
to Web client users as soon as the new application is available.
After the cut-down model job runs, the Finish window is displayed and the final step in the Go to
Production process is started automatically.
During the final stage of Go to Production, the following processes occur.
Stage
Datastore Backup
Description
A datastore backup is made if this option was selected and happens
after the cut-down models process.

Stage
Preproduction Processes
Go to Production
Post Production Tasks
Description
● A master model definition per language is produced.
● New e.List items are added to datastore tables.
● Import data blocks are associated with the production application.
● Error trapping takes place, for example, if there are no e.List
items, Go to Production does not take place.
● The development and production model definitions are unpacked
and loaded into memory.
● Two e.List items are reconciled as a test. Most errors in reconcili-
ation occur when the first e.List items are reconciled.
● The switch-over from the development to the production applic-
ation is performed. During this stage, the system takes the
application offline temporarily to ensure data integrity. The new
e.List item workflow states are determined during this time to
correctly process any e.List hierarchy changes. As soon as those
changes are applied it the application becomes online again and
the post-production processes are started. This offline period is
typically so short that it is transparent to users, but it can some-
times exceed one minute.
● The workflow state is refreshed to include new items.
● The new application is put into production.
● The Web application is restarted and users can now submit.
● Any e.List items that were removed are deleted from the datastore.
● Completed jobs that are no longer relevant are removed from the
job list, such as a publish of a previous production application.
A message that tells you that you successfully put the development
application into production.
Chapter 14: The Go to Production Process
Administration Guide 257

Chapter 14: The Go to Production Process
258 Contributor
Stage
Description
Then the following operations are performed:
● Obsolete cut-down models are removed by the cut-down tidy job.
● Old import data blocks are removed.
● A validate_users job is run to check that the current owner or
editor of an e.List item can still access the e.List item.
● Redundant copies of translations from the previous production
application are removed by the language_tidy job.
● If reconciliation is required, it is queued and run as soon as job
servers are started and set up to monitor the application.
Note: If you set the production application offline before running the
Go to Production process, it is offline when the Go to Production
finishes running. If the production application is online before running
Go to Production, it is online when Go to Production finished.

Chapter 15: Publishing Data
You can publish the data collected by IBM Cognos 8 Planning - Contributor to a datastore, either
from the Administration Console, or using the publish macros (p. 211).The data can then be used
either as a source for a data mart or warehouse, or with IBM Cognos 8 studios. The publish process
creates a datastore containing tables and views based on the publish layout and options that you
select.
Publish Layouts
Choose from these types of publish layouts: table-only, incremental, and view.
● The table-only layout gives users greater flexibility in reporting on Planning data. The table-
only layout can also be used as a data source for other applications. This layout is required by
the Generate Framework Manager Model Admin extension (p. 306) and the Generate Transformer
Model Admin extension (p. 309).
● The incremental publish layout publishes only the e.List items that contain changed data. Users
can schedule an incremental publish using a macro (p. 216) or through IBM Cognos Connection
and Event Studio. You can achieve near real-time publishing by closely scheduling incremental
publishes.
● The view layout generates views in addition to the export tables. This layout is for historical
purposes.
The Publish Process
Publishing data is a production task that can only be performed after you run Go to Production
and all e.List items that you are publishing are reconciled. You can monitor the progress of the
e.List items being reconciled in the Preview window (p. 293). If you are setting data dimensions for
publish for the view layout, you must do this before you run Go to Production. This is not necessary
for the table-only layout.
When you publish data, the following things happen:
● A publish container is created, if one does not already exist.
● An accurate snapshot is taken of the data at the time a publish is run to ensure a consistent
read.
● A publish job runs. This creates tables in the datastore, depending on the layout and options
selected. For more information, see "Jobs" (p. 49).
You can run a publish at the same time as an administration link (p. 147).
Administration Guide 259

Chapter 15: Publishing Data
The Publish Data Store Container
You must publish to a separate publish container. This is because the main application container
holds the transactional planning data in compact XML binary large object (blob) format, and must
be backed up on a regular schedule based on the lifecycle of the transactional application.
The publish container contains a snapshot of the planning data in relational form, which is a different
lifecycle and contains a significantly different storage and performance profile. By having separate
publish containers, you can make use of dedicated job servers for publish datastores. The two
available publish layouts cannot coexist in a single datastore container.
Access Rights Needed for Publishing
Publish Scripts
260 Contributor
You must be granted rights to publish data for the application (p. 39). If this is the first time you
run publish, you can either publish to the default publish container, or create a new publish container.
The default publish container resides on the same datastore server as the application with the same
tablespace settings (for Oracle and DB2 UDB).
For publish to be processed, the publish container must be added to a job server cluster or job server
(p. 58). Therefore you must either have the right to create a publish container, and assign objects
to a job server, or the publish container must be created and added to the job server already (p. 39).
You may need to create publish scripts before you can publish data if you do not have DBA rights
to your datastore server.
To generate publish scripts, the Generate Scripts option must be set to Yes in the Admin Options
table (p. 180).
If you attempt to publish but a publish container does not exist, a script is generated. A DBA must
then run the script to create the container. A message indicating the location of the script is shown.
If the publish container does exist, a check is run to see if there are any datastore incompatibilities.
If there are incompatibilities, another script is generated. Incompatibilities occur if you republish
a datastore, and the format of the metadata has changed between publishes. For example, a cube
was added, data dimensions changed, items were added to the Analyst model. There are always
incompatibilities on the first publish, since the metadata tables are not present.You cannot publish
until this script is run to update the datastore.
You can generate a synchronization script manually by clicking the Generate synchronization script
for datastore button.
Warnings
You may receive a warning similar to the following when running a script generated by Table-only
layout publish, when the Generate Scripts option is selected:
"Warning: The table 'annotationobject' has been created but its maximum row size (8658) exceeds
the maximum number of bytes per row (8060). INSERT or UPDATE of a row in this table will fail
if the resulting row length exceeds 8060 bytes."

The table definition allows for a large amount of data to be stored per row. SQL Server generates
a warning to let you know that there is a limit on how much data you can have on a row. If your
annotation data exceeds this limit then your publish will fail. You can reduce the amount of data
by selecting a smaller data dimension or by reducing the amount of data in the system, for example
by using Delete Commentary.
Selecting e.List Items to Be Published
When you publish data, select the e.List items that you want to publish.
● For a View layout, you can import the e.List item publish settings in the e.List import file. If
you do this, select the Copy development e.List item publish settings to production application
option. When you run Go to Production, the publish settings are copied to the e.List items tab.
If you have not imported the publish e.List item settings, you can also set them on the e.List
items tab.
● For a Table-only layout, you must set the publish e.List item settings on the e.List items tab.
Reporting Directly From Publish Tables
IBM Cognos Planning published data is stored in standard datastore tables. You can report directly
from these tables, using the Generate Framework Manager Model functionality to help in the process.
You must not run reports during the publish process, as you may get inconsistent results. Also, if
destructive changes have been made to the Planning environment, the publish tables may no longer
match the ones defined in your reporting metadata model.
It is best practice to isolate the business intelligence reports from the source data environments by
creating a reporting datastore. This allows you to add value by bringing in data from other applic-
ations. For example, perhaps there is some data which was optimized out of the IBM Cognos
Planning application but would be useful for your reports.
At its simplest, this datastore could be a straight copy of the publish tables as produced by IBM
Cognos Planning. It could also be a traditional data mart or an extension to your existing data
warehouse. Dimensionally-aware ETL tools such as IBM Cognos Data Manager can also be used
to ensure that a single version of data runs through all your IBM Cognos Planning and business
intelligence applications.
If you report directly from IBM Cognos Planning tables, be aware of the following:
Scenario and Version Dimensions
IBM Cognos 8 is usually set up to automatically aggregate data around grouped items. If your
report does not contain all the dimensions from a fact table then the data for the unspecific
dimensions is aggregated.
Normally, this is desirable behavior, but the Scenario and Version dimensions that are often used
in planning applications are not suited for aggregation. One technique to handle this is to set up a
mandatory filter on your cube tables in Framework Manager, forcing the reporting environment
to either prompt for values whenever the fact table is used, or to have separate filtered query subjects
for each version.
Chapter 15: Publishing Data
Administration Guide 261

Chapter 15: Publishing Data
Precalculated Summaries
Be aware of precalculated summary levels in the published tables when using the Table-only publish
layout. You may find that they complicate your data model. You can disable them by clearing the
Include Roll Ups publish option.
If you do not do this, then the data for precalculated summary levels is published into the same
tables as the detail items. If you are using item tables (named it_D-List_name and containing an
unstructured flat list of all items in the hierarchy) this is acceptable. If not, you may have reporting
issues as your queries need dimensional context in order to avoid double counting.
Note also that the publish take longer to run (more data points to write). If you are not using the
item tables then the reporting environment could confuse users because there are separate hierarchy
table aliases for each level in Framework Manager.
Model Changes that Impact the Publish Tables
262 Contributor
IBM Cognos Planning models are flexible and change to map the changes in the business. Changes
can affect reports that are run off planning data. The following tables describe the impact that
various changes to the Planning model have on publish tables in the data.
Changes to D-Lists that are used as D-List formatted items result in fact table name change.
Change to Dimension
Add items
Delete items
Rename items
D-List (not Dimension for Publish)
None as long as the number of
levels in the hierarchy remain the
same.
None as long as the number of
levels in the hierarchy remain the
same.
None unless name filters are used
in the BI application.
Dimension for Publish
New columns added. Existing SQL
still works.
Columns are deleted. Processing
referring to these columns must be
modified.
D-List formatted items are stored
in the fact columns as text rather
than as a foreign key. As a result,
text exported from previously
published data may not match this
text.
A full publish resets the text in the
Publish tables, but review external
datastores where these items have
not been normalized.

Change to Dimension
Add hierarchy levels
Delete hierarchy levels
Reorder items
Refresh items from
the datastore
Rename the D-List
Change to D-Cube
Reorder dimension
Add dimension
Delete dimension
D-List (not Dimension for Publish)
New columns created in dimension
tables. Existing reports will not fail
but level naming may no longer be
correct.
Columns deleted in dimension
tables.
None.
None.
Dimension table name changes.
Affect
Dimension for Publish
None.
None.
Datastore columns are reordered
but SQL still works.
SQL still works.
None, as long as the D-List is not
used in D- cube where it is not the
dimension for publish.
None. The column sequence in the datastore may change but this does
not impact reports.
Assuming that the new dimension is not the dimension for publish, data
for all items in the new D-List are automatically summed if no action is
taken.
Data Dimensions for Publish
For most lists this is desirable, but care needs to be taken if the dimension
contains scenarios or versions.
Links to the dimension table are removed from the fact table. Reports
referring to items in that dimension are affected.
Setting data dimensions for publish can reduce the volume of published data considerably.
In both layouts, for each selected D-Cube, you can choose a D-List that is designated as the
dimension for publish. A separate column is created for each data item in the dimension. Selecting
a dimension speeds the publishing process because fewer rows are written to the target database.
Candidate dimensions for publish typically contain formatted D-List items or items by which the
business tracks or measures performance. Such items are often numeric.
Chapter 15: Publishing Data
Administration Guide 263

Chapter 15: Publishing Data
For a View layout, set dimensions for publish in Development, Application Maintenance, Dimensions
for Publish. Setting a data dimension is optional only for View layout, and changes to dimensions
for publish apply only after you have run Go to Production. If the dimension that is used as a data
dimension is removed in IBM Cognos 8 Planning - Analyst and the application is synchronized, the
synchronization process handles this.
It is mandatory to select a data dimension for publish for the Table-only layout. If you do not select
one, a default dimension is used. This is a dimension that has formats defined. If you have more
than one dimension with formats, ensure you select the one you require. If you plan to use Contrib-
utor data as a source for IBM Cognos 8 Business Intelligence Studios, the dimension you select for
a cube is the one used as the measure dimension in IBM Cognos 8. The PPDS driver also uses a
dimension for publish. If one is set on the cube, it is used as the measure dimension in IBM Cognos 8.
We recommend that each item of the selected dimension contain uniform data. This means that for
every row, the data is of the same type: numeric, text, or date/time.
Handling Nonuniform Data in Table-only Publish
Slicing the D-Cube along the dimension for publish may result in nonuniform data. For example,
cell data along any item of the dimension for publish may be of mixed types. Because of this, rows
of data for an item may be of different types.
In the table-only layout, where nonuniform data exists and must be preserved, if you select Create
columns with data types based on the "dimensions for publish", it automatically creates enough
columns so that no data is excluded. However, if you manually choose the columns to create, only
the data in the format selected is published. For example, selecting the numeric and date/time options
guarantees that only numeric and date/time data are written to the corresponding numeric and
date/time columns; text is excluded. As a result, if the first row of an item is a numeric value, it is
stored in the corresponding numeric column. The remaining data type columns for that item are
populated with null values.
In the view layout, data type uniformity is handled by storing all values in text columns. An associ-
ated fact view (fv) is created using the sum hierarchy to view only numerical information.
Selecting a Dimension for Publish for Reporting
264 Contributor
It is important to carefully consider which dimension for publish you select when publishing data
to be reported on. The dimension for publish is the D-List whose items become columns in the fact
table. That is, instead of becoming an ID which links to a hierarchy table, the items in the selected
D-List are converted to actual fact table columns.
Why the Choice of Dimension for Publish is Important
If you are reporting using a non-OLAP reporting tool, the publish is performed using SQL behind
the scenes. Data is reported in columns, which are sorted, grouped and summarized in the rows.
This means that you can perform actions such as inter-column calculations and independent
formatting in the columns, but the rows can only be summarized. You can potentially build SQL
reports with intra-row calculations, but it would take you longer to build and costs more to maintain.
Note that rows and columns here are SQL terms. Columns and rows can be switched around within
a report, and indeed this is often the case in financial reports.

Selecting Your Dimensions for Publish
The primary calculation D-List is often used as the dimension for publish. However there are situ-
ations where other D-Lists (such as Time or Versions) are more suitable.
Your choice of dimension for publish is driven by a number of factors, and the Planning and BI
designers should work together to select the appropriate one for reporting. The Planning designer
may find it easier to build another cube than to report from an existing cube.
Carefully consider which dimension for publish to use, because if you change it after you have
started to build reports, you may need to rework existing reports.
The following D-List attributes identify a likely dimension for publishing:
● It contains a combination of text, numeric and date items (mixed data types).
● It contains numeric items with different display formats such as ##% and #,###.##.
● Your reports need to do additional calculations between items in the D-List.
● You need to treat some of the D-List fields separately for reporting purposes.
● The dimension for publish impacts the time the Publish takes to run. Even though there are
fewer columns to create, more rows are written to the datastore, and this takes time to write.
Tip: In some circumstances you may not want a dimension for publish. In this case your publish
table has one row for every combination of dimension and you would leave all the processing
and formatting intelligence to the reporting tool. Using the Table-only layout, you must select
a dimension for publish, so to achieve equivalent functionality, add a D-List to the cube con-
taining one item, and use this D-List as the dimension for publish.
The Table-Only Publish Layout
Using the table-only publish layout, you can
● generate data columns in their native order, which preserves the original order when reporting,
as when you publish to a view layout
● publish detail plan data
● select whether to prefix the dimension for publish column names with their data type to avoid
reserved name conflicts
When using the Generate Framework Manager Model Admin extension (p. 306), the table-only
publish layout must be used.
The following types of tables are created when you publish using the table-only layout.
Table type
Attached Documents
Description
Contains metadata about the
attached documents
Prefix or name
Ad_ for cell attached documents, doc-
umentobject for tab (cube) and model
attached documents
Chapter 15: Publishing Data
Administration Guide 265

Chapter 15: Publishing Data
Table type
Items (p. 267)
Hierarchy (p. 267)
Export (p. 270)
Annotation (p. 271)
Metadata (p. 274)
Common (p. 276)
Job (p. 276)
Object locking (p. 277)
Publish parameter
Database Object Names
266 Contributor
Description
Describes the D-List items.
Contains the hierarchy inform-
ation derived from the D-list,
which is published to two
associated tables.
Contains published D-Cube
data.
Contains annotations, if the
option to publish annotations
is selected.
Contains metadata about the
publish tables.
Contains tables used to track
when major events occurred in
the publish container.
Contains tables with informa-
tion relating to jobs.
A table used to lock objects in
the system when they are being
processed.
Contains state information
related to table-only publish
Prefix or name
it_
sy_ for the simple hierarchy
cy_ for the calculated hierarchy.
et_
an_ for cell and audit annotations
annotationobject for tab (cube) and
model annotations
P_APPLICATIONCOLUMN
P_APPCOLUMNTYPE
P_APPOBJECTTYPE
P_APPLICATIONOBJECT
P_ADMINEVENT
P_ADMINHISTORY
P_CONTAINEROPTION
P_JOB
P_JOBITEM
P_JOBITEMSTATETYPE
P_JOBSTATETYPE
P_JOBTASK
P_OBJECTLOCK
publishparameters
are derived from the Planning object names. The maximum length of table and column names are
as follows.

Type of Name
Column
Table
MS SQLServer
128
128
IBM DB2 UDB
30
128
Oracle
Names cannot begin with a number or underscore (_), and can include the following characters:
● a through z
● 0 through 9
● _ (underscore)
Items Tables for the Table-only Layout
One items table is created for each D-List. It contains one row per item. The name of the table is
generated from that of the D-List and the prefix it_.
The items tables have the following columns.
Column
itemid
itemname
displayname
disporder
itemiid
Description
Unique identifier for the item
Name of the Item
Display name of the item
Display order specified in Analyst, which is zero-based
D-List integer identifier for the item, which is used as the
primary key
Hierarchy Tables for the Table-only Layout
The complete hierarchies are published to the cy tables while the simple summary hierarchies are
available in the sy_ tables.
These tables all have the same format. They contain the following columns for each level of the
hierarchy.
Column
levelLevelNumber_guid
levelLevelNumber_iid
levelLevelNumber_name
Description
30
30
Globally unique identifier of the item
D-List integer that identifies the item
Item name
Chapter 15: Publishing Data
Administration Guide 267

Chapter 15: Publishing Data
Column
levelLevelNumber_displayname
levelLevelNumber_order
Description
Item display name
Item order in the hierarchy
Simple hierarchy tables are created by the publish table-only layout. They are intended to be used
when there are simple parent-child relationships between D-List items that can be summed. The
purpose of this is to allow a reporting tool to automatically generate summaries for each hierarchy
level, or for use with applications that do not require precalculated data, such as a staging source
for a data warehouse.
In the following examples, D-List items are represented by letters, and the relationships between
items are drawn as lines.
Parent D-List items are calculated from child D-List item dependencies. Leaf D-List items do not
have child D-List item dependencies.
All D-List items have their values shown in simple parenthesis and in addition, leaf D-List item
codes are shown in curly braces.
D-List Value
0
1
2
3
Example 1 - Simple Summaries
268 Contributor
Description
Direct child of a simple sum D-List item.
The leaf has multiple parents.
The leaf item is part of a sub-hierarchy that has been moved
to the root (no parent).
The leaf item is an orphan.
The left pane is an example of simple hierarchies with values. The right pane is an example of simple
hierarchies with values and leaf D-List item codes.

Example 2 - Leaf D-List Item with Multiple Parents
In the left pane, [E] has more than one parent, so parentage is assigned to the first parent in the IID
order. In the right pane, [D] becomes a leaf D-List item, and [F] becomes orphaned and is moved
to the root in the right pane.
Example 3 - Non-Simple Summaries
In the left pane, [P] is the product of [S] and [T]. Leaf D-List items of non-simple summaries get
moved to the root. In the right pane, [P] became a leaf D-List item, [S] and {T] were orphaned and
moved to the root in the right pane.
Chapter 15: Publishing Data
Administration Guide 269

Chapter 15: Publishing Data
Example 4 - Sub-Hierarchy of Non-Simple Summary
In the left pane, [B] is the product of [C] and [E]. [C] has its own simple summary hierarchy. Because
non-simple sums are not included in the hierarchy, in the right pane, [B] becomes a leaf, [E] and
[C] become orphaned and moved to the root, and [C] keeps its sub-hierarchy because it is a simple
sum.
Export Tables For the Table-only Layout
270 Contributor
Cell data for the selected cubes is published to the export tables.
If you select the Include Roll Ups option, the export tables contain all the data, including calculated
data.
If you do not select this item, the export tables contain only non-calculated fact data.
Users who report against published data that contains only fact data use the reporting tool to
aggregate the calculated items when grouping with the hierarchical dimensions.
You can control how the export tables (prefix et_) are generated as follows.
● Publish only uniform cube data. Select the Create Columns With Data Types Based on the
Dimension for Publish option, the data type of each item of the Dimension for publish is used
for the columns of the export tables. If individual cell types differ from that of the corresponding
columns, the corresponding cell data is not published and an informative message appears.
● Select only data of the specified types.
When more than one data type is selected, multiple columns appear for each item in the export
tables, one column per data type. For example, if both numeric data and dates are selected,
two columns are created per item in the dimension for publish.
● Include the original formatted numeric and date values, which are stored in the text column.
This is useful when the original format cannot be easily reproduced in the reporting tool
application.
● Publish entire cubes, or publish only leaf data and let the reporting engine perform the rollups.
In this way, you control the level of detail of the information to publish.

Data Types Used to Publish Data
The summary hierarchy as specified in the sy_ tables must be used to perform the rollups. Leaf
cells are those that correspond to leaf items of the simple summary hierarchies.
The following data types are used for publishing data.
Data type
TEXT
DATE
DOUBLE
INTEGER
MS SQLServer
VARCHAR(8000)
datetime
float
integer
IBM DB2 UDB
CLOB
date
float
int
Oracle
VARCHAR2(4000)
timestamp
float
NUMBER(10)
The prefixes text_, date_, and float_ are used to identify the data types of columns in tables, and
the suffix _[count] is used to guarantee name uniqueness.
Annotations Tables for the Table-only Layout
The an_cubename Table
You can choose to publish user and audit annotations.
Cell and audit annotations are published to the an_cubename table.
Tab and model annotations are published in the annotationobject table.
This table contains cell and audit annotations.
The columns of the an_cubename table are as follows:
Column
HierarchyDimensionName
Dimension_DimensionName
MeasureDimensionItem-
Name_user_id
DimensionItemName_date
Description
The unique identifier (p. 267) of the e.List items for the
coordinates of the cell annotations.
The unique identifier of the D-List items for the coordinates
of the cell annotations.
The last user who updated the annotation.
The last date the annotation was updated.
Chapter 15: Publishing Data
Administration Guide 271

Chapter 15: Publishing Data
Column
DimensionItemName_annotation
DimensionItemName_value
visible
The annotationobject Table
Description
For a cell annotation, the text of the annotation.
For an audit annotation, the details of the action performed.
The text is prefixed with Audit annotation on … followed
by the action.
This table contains tab and model annotations.
The cell value at the time of the annotation.
Indicates if this row can be reported on.
The columns of the annotationobject table are as follows.
Column
object_id
node_id
user_id
annotation_date
annotation
Description
The identifier of the cube or model being annotated.
The e.List item identifier.
The user id of the person who created the annotation.
The date and time the annotation was made. They are
stored as UTC + 00:00.
The text of the annotation.
Attached Document Tables for the Table-only Layout
The ad_ cubename Table
272 Contributor
You can choose to publish some metadata about the attached document. Cell level attached document
metadata is published to the ad_cubename table. Tab and model attached document metadata is
published in the documentobject table.
This table contains cell attached document metadata.
The columns of the ad_cubename table are as follows.
Column
HierarchyDimensionName
Description
The unique identifier (p. 193) of the e.List items for the
coordinates of the cell attached documents.

Column
Dimension_DimensionName
MeasureDimensionItem-
Name_user_id
DimensionItemName_date
DimensionItemName_filename
DimensionItemName_filesize
DimensionItemName_comment
DimensionItemName_value
visible
The documentobject Table
Description
The unique identifier of the D-List items for the coordinates
of the cell attached documents.
The last user who updated the attachment of the document.
The last date the attachment of the document was updated.
The file name of the document that was attached.
The file size at the time the document was attached.
A comment that was entered at the time the document was
attached.
The cell value at the time the document was attached.
Indicates if this row can be reported on.
This table contains tab and model metadata about attached documents.
The columns of the documentobject table are as follows.
Column
node_id
object_id
user_id
document_date
document_name
document_size
document_comment
visible
Description
The e.List item identifier.
The identifier of the cube or model that is having the docu-
ment attached to it.
The user id of the person who attached the document.
The date and time the document was attached.
The file name of the document that was attached.
The file size at the time the document was attached.
A comment that was entered at the time the document was
attached.
Indicates if this row can be reported on.
Chapter 15: Publishing Data
Administration Guide 273

Chapter 15: Publishing Data
Metadata Tables
Metadata about the publish tables is maintained in several tables.
The P_APPLICATIONOBJECT Table
The description of each database object created during a publish operation is maintained in
applicationobject.
The columns of the P_APPLICATIONOBJECT table are as follows.
Column
objectname
displayname
objectid
objecttypeid
datastoretypeid
objectversion
lastsaved
libraryid
The P_APPLICATIONCOLUMN Table
274 Contributor
Description
Name of the object.
Display name of the associated Planning object.
A globally unique reference (GUID) for the object.
The type of object, for example, EXPORT_TABLE,
DIMENSION_SIMP_HIER.
Describes the datastore type: Table.
This is an internal version number used for debugging.
This detects if the published model is out of date.
This detects if the published model is out of date.
The columns of the P_APPLICATIONCOLUMN table are as follows.
Column
objectname
columnname
displayname
columnid
objecttypeid
columntypeid
Description
Name of the object.
Name of the column.
Display name of the associated Planning object.
A globally unique reference (GUID) for the object.
Type of Planning object, such as, EXPORT_TABLE,
DIMENSION_ITEMS, DIMENSION_SIMP_HIER.
-

Column
columnorder
logicaldatatype
The P_APPCOLUMNTYPE Table
Description
The types of tables that can exist in Contributor.
The columns are as follows:
Column
objecttypeid
columntypeid
description
The P_APPOBJECTTYPE Table
The types of application object that exist.
The columns are as follows:
Column
objecttypeid
description
The dimensionformats Table
The order in which the column appears.
The type of data, such as, epGUID, epTextID.
Description
The object type, such as a FACT_VIEW.
-
A description of the object type.
Description
The object type, such as ANNOTATION_OBJECT.
A description of the object type.
The dimensionformats table formatting information for the items of the dimension for publish that
is compatible with IBM Cognos 8 Business Intelligence.
The columns of the dimensionformats table are as follows.
Column
dimensionid
itemguid
formattype
negativesignsymbol
Description
Globally unique identifier of the dimension for publish.
Globally unique identifier of the item of the dimension for
publish.
One of percent, number, or date.
Chapter 15: Publishing Data
String indicating how negative values must be reported.
Administration Guide 275

Chapter 15: Publishing Data
Column
Common Tables
Job Tables
276 Contributor
noofdecimalplaces
scalingfactor
zerovaluechars
Description
Number of decimal places for numerical values.
Integer for the scaling factor of numerical values.
Characters to use for zero of blank value.
Common tables are created so that you can track the history of events in the publish container.
The P_ADMINHISTORY table stores information about when major events occurred to the publish
container.
The P_ADMINEVENTS table contains the IDs and descriptions of the event types used in the
P_ADMINHISTORY table.
The P_CONTAINEROPTION table is used for Oracle and DB2 to store tablespace information
for blob, data, and index.
The following tables are created to support jobs (p. 49).
Table
P_JOB
P_JOBITEM
P_JOBITEMSTATETYPE
P_JOBSTATETYPE
P_JOBTASK
P_JOBTYPE
Description
Information about the jobs that are running or ran in the
application. This information is used in the Job Manage-
ment window.
Each Job Item is represented by a row in the jobitem table.
The state of the Job Item is also stored. If a problem
occurred while running the Job Item, descriptive text is
stored in the failurenote column and is appended to the
failurenote column for the job.
Job item status types: failed, ready, running, succeeded.
Job status types: canceled, complete, creating, queued,
ready, running.
Where and when the job items ran and the security context
it used.
Job types and their implementation program IDs.
Parameters and failurenotes in Job tables are stored as XML LOBs.

The P_OBJECTLOCK Table
The P_OBJECTLOCK table supports macros, administration links, and the export queue. It locks
objects in the system when they are being processed and contains information about the objects
being worked on.
Create a Table-only Publish Layout
Before you publish, you must ensure the following
● you have appropriate access rights (p. 260)
● the Go to Production process has been run (p. 243)
Note: You can increase publish performance by managing or dropping indexes during the publish
process. You can set this option in Development, Application Maintenance, Admin Options. For
more information, see "Admin Options" (p. 79).
Steps
1. In the application's tree, click Production, Publish, Table-only Layout.
2. Check the cubes you want to publish data from.
● The Dimension column indicates the data dimension for publish that is selected.
● The Annotation Rows column shows the number of annotation rows for a cube when you
click Display row counts.
● The Export Rows column shows the number of rows that are published when you click
Display row counts.
3. Click the e.List Items tab.
You can select or clear individual items, or use the buttons at the top of the table.
This step is not required for assumption cubes because assumption cubes do not contain e.List
items.
4. To set the Publish options and configure the Publish datastore connection, click the Options
tab (p. 278).
5. Click Publish.
6. If you are asked if you want to create a publish container, click OK.
7. Select the job server or job server cluster to monitor the publish container and click Close.
You need the rights to add an application to the job server or job server cluster.
A reporting publish job is queued. You can monitor the progress of the job. For more information,
see "Jobs" (p. 49).
Chapter 15: Publishing Data
Administration Guide 277

Chapter 15: Publishing Data
Options for Table-only Publish Layout
278 Contributor
In the Publish Options tab, you can set the publish options and configure the publish datastore
connection.
Option
Creating a New Publish Container
Configuring the Publish Datastore
Connection
Create columns with data types
based on the ’dimension for publish’
Only create the following columns
Include Roll Ups
Include Zero or Blank Values
Prefix column names with data
types
Include User Annotations
Include Audit Annotations
Description
The first time you attempt to publish data, you can either
create the default publish container, by clicking Publish, or
create a new publish container (p. 285).
To configure the publish datastore connection, click the
Configure button, see (p. 286).
To use the item types from the dimension for publish as the
table columns.
To manually select the data types that are part of the pub-
lish process for each measure.
You can choose to publish Numeric, Text, and Date
columns. Within the Text column, you can also choose
whether to include formatted numeric and date values.
Selecting this check box includes all items, including calcu-
lated items. Clearing this option only publishes leaf items,
and therefore fewer rows. You can recreate the calculation
in your reporting tools by linking the et and sy tables.
Clearing this check box means that empty cells are not
populated with zeros or blanks. This can speed up the
process of publishing data substantially, depending on the
number of zero or blank cells.
Select this option if you wish the column name to be pre-
fixed with the data type to avoid reserved name conflicts.
Selecting this check box publishes cell level user annotations
in a table named an_cubename.
Selecting this check box publishes audit annotations in a
table named an_cubename, in the column annota-
tion_is_edit.

Option
Include Attached Documents
Create an Incremental Publish
Description
Selecting this check box includes information about attached
documents. Information about the attached document such
as the filename, location, and file size are published with
the data.
If you are publishing data using the Table-only layout, the Incremental Publish feature can be used
to only publish those e.List items that have changed since the last time you published. Incremental
Publish uses the same infrastructure as Table-only layout but tracks what items were altered since
the last publish and only re-publishes them. You can create macros that will run an incremental
publish at scheduled intervals, see "Publish - Incremental Publish" (p. 216). This provides you with
a nearly real-time publish. Another benefit of scheduling incremental publishes is that you can
publish changed data soon after saving or submitting plans. It also reduces the need for frequently
scheduled full publishes and therefore potentially saving time and resources.
If your publish selection contains more than one cube, but values change in only one cube, the
changed e.List items for all the cubes are republished. The incremental publish is by definition a
change-only publish and therefore requires that a publish schema is created, either by running a
full publish, selecting the cubes and e.List items that you want to publish, or by generating and
running publish scripts. When you run a Go to Production process incremental publishes that are
changes-only are suspended. Model changes that result in changes to the publish schema may require
you to do a full publish of all the selected cubes and e.List items.
Steps
1. In the application's tree, click Production, Publish, Incremental Publish.
2. To configure the publish container, click Configure.
The incremental updates will be applied to that container.
3. To publish only submitted changes, select Include only submitted items.
Note: If you use this option without changing data in an e.List, the e.Lists without changes are
not included in the publish.
4. Click Publish.
A message displays indicating if an Incremental Publish job was initiated or, if no changes were
detected.
The View Publish Layout
The view publish layout as supported in Contributor and Analyst version 7.2 is compatible with
previous Planning data solutions. It is intended for backwards compatibility only.
Chapter 15: Publishing Data
Administration Guide 279

Chapter 15: Publishing Data
We recommend that non-IBM Cognos applications currently dependent on the view publish layout
be migrated to use the new table-only publish layout because of the improvements in publish per-
formance, data storage efficiency and incorporation of best practices.
The following types of publish tables are created when you publish using the view layout:
Table type
Items (p. 281)
Hierarchy (p. 281)
Export (p. 282)
Annotation (p. 282)
Metadata (p. 274)
Common (p. 276)
Job (p. 276)
Database Object Names
280 Contributor
Description
Describes the D-List items.
Used by reporting tools. The depth
of each item in the dimension hier-
archy is recorded and display
information.
Contains published D-Cube data.
Contains annotations, if the option
to publish annotations is selected.
Contains metadata about the
tables.
Contains tables used to track when
major events occurred in the pub-
lish container.
Contains tables with information
relating to jobs.
Prefix or Name
it_
hy_
cy_ (calculation hierarchy tables)
et_
an_ for cell and audit annotations
annotationobject for tab (cube) and
model annotations
P_APPLICATIONCOLUMN
P_APPCOLUMNTYPE
P_APPOBJECTTYPE
P_APPLICATIONOBJECT
annotationobject
P_ADMINEVENT
P_ADMINHISTORY
P_CONTAINEROPTION
P_JOB
P_JOBITEM
P_JOBITEMSTATETYPE
P_JOBSTATETYPE
P_JOBTASK
P_OBJECTLOCK
Database object names are limited to 18 lowercase characters, and are derived from the IBM
Cognos 8 Planning object names.

Items Tables for the View Layout
One items table is created for each D-List. It contains one row per item. The name of the table is
generated from that of the D-List and the prefix it_.
The items tables have the following columns.
Column
itemid
dimensionid
itemname
displayname
disporder
Hierarchy Tables for the View Layout
Description
Unique identifier for the item.
Unique identifier for the D-List.
Name of the item.
Display name of the item.
Display order specified in Analyst, which is zero-based.
There is no model construct for specifying items hierarchies. Instead, hierarchies are derived from
user specified equations.
Two types of hierarchies are currently supported; complete hierarchies and simple summary hier-
archies.
Complete hierarchies are used to produce reports on the entire contents of cubes. Complete hier-
archies are used to organize cube data and are not used to perform rollups and calculations in the
reporting engine. The rules that govern the generation of complete hierarchies in the cy_ tables are
as follows:
● The parent of a given item is the first simple sum that references the item.
● If this sum does not exist, it is the first non-sum calculation that references the item.
● If neither exists, the item is a top-level item.
Simple summary hierarchies are used when only detail items are published and rollups are performed
from the reporting engine. The rules that govern the generation of these hierarchies are as follows:
● The parent of a given item is the first simple sum that references it.
● If there are there are multiple candidates for the parent of an item, it is assigned to the first
parent in iid order and the other candidate parents are considered to be detail items in the
hierarchy.
● In the case where a parent cannot be identified that way and the item is not a simple sum, it is
considered to be a root item.
Simple summary hierarchies are not necessarily complete because all items that are part of a D-List
may not necessarily be part of the hierarchy.
Chapter 15: Publishing Data
Administration Guide 281

Chapter 15: Publishing Data
The starting point for the production of these hierarchies is the graph of items dependencies produced
when equations are parsed. This graph specifies all parent/child relationships between items. Because
the simple summary hierarchy is limited to simple sums, sub-hierarchies can be detached from the
main hierarchy and moved to the top.
Export Tables for the View Layout
Cell data for the selected cubes are published to the et_ tables, one row per cell. These tables contain
the coordinate for each cell of the cube and the corresponding cell value. One column per D-List
stores the item GUID along that dimension. An additional column stores the cell value (published
as a blob or varchar depending on the target DBMS). In IBM Cognos 8 Planning, a cell value can
contain a date, a double, or text.
Annotation Tables for the View Layout
You can choose to publish user and audit annotations.
Cell and audit annotations are published to the an_cubename table.
Tab and model annotations are published to the annotationobject table.
The an_ cubename View Layout Table
The an_cubenameview layout table contains cell and audit annotations.
The columns of the an_cubename table are as follows.
Column
Dimension_DimensionName
HierarchyDimensionName
annotation_user_gu
annotation_date
annotation_cell_va
annotation_is_edit
The annotationobject View Layout Table
282 Contributor
Description
The unique identifier of the D-List items for the coordinates
of the cell annotations.
The name of the e.List.
The globally unique identifier of the last user who updated
the annotation.
The date and time the annotation was made. They are
stored as UTC + 00:00.
The cell value at the time of the annotation.
Whether the annotation is editable (0 = no, 1 =yes).
The annotationobject view layout table contains published tab and model annotations.
The columns of the annotationobject table are as follows.

Views
Column
objectguid
nodeguid
user_guid
annotation_date
annotation
Description
The globally unique identifier (GUID) of the cube or model
being annotated.
The GUID of e.List item being annotated.
The GUID of the user that annotated.
The date and time the annotation was made.
The text of the annotation.
An ev_view is created to provide a more user-friendly access to its associated export table (et_table),
which contains cube data. In this view, GUIDs are simply replaced by the display name associated
with the D-List items, and export value are cast to varchar when published as blobs.
A fact view (with fv_prefix) is created for each cube being published and is limited to numeric values
by joining the export values from the et_ table to the items in the hy_ tables for the cube. These
rules for deriving this hierarchy are explained earlier.
A complete view (with cv_prefix) is created for each cube being published and is built by joining
the export values from the et_ table to the items in the cy_ tables for the cube.
The following views are created in a view publish layout.
View name
fv_cubename
ev_cubename
av_cubename
cv_cubename
Create a View Layout
Description
A view on the cell data for a cube that resolves the star
schema linking to the flattened out hierarchy for a dimen-
sion.
Before you publish, you must ensure that
A view on the cell data for a cube that resolves the star
schema linking to the items in a dimension.
A view on the cell annotations table for a cube that resolves
the star schema.
● you have appropriate access rights (p. 260)
● select the data dimensions for publish, if required (p. 263)
Chapter 15: Publishing Data
A complete view created for each cube being published.
Administration Guide 283

Chapter 15: Publishing Data
● select the e.List items to be published (p. 261)
● Go to Production was run (p. 243) after the data dimensions for publish were selected
Note: You can increase publish performance by managing or dropping indexes during the publish
process. You can set this option in Development, Application Maintenance, Admin Options. For
more information, see "Admin Options" (p. 79).
Steps
1. In the application tree, click Production, Publish, View Layout.
2. On the Cubes tab, check the cubes you want to publish data from.
● The Dimension column indicates the dimension that is selected.
● The Annotation Rows column shows the number of annotation rows for a cube when you
click Display row counts. Note that only cell annotations are published.
● The Export Rows column shows the number of rows that are be published when you click
Display row counts.
3. Click the e.List Items tab to select the e.List items to publish. You are unable to publish before
doing this.
4. Click the Options tab. This step is optional and enables you to set the Publish options and
configure the Publish datastore connection. For more information, see "Options for View
Layout" (p. 284).
5. Click Publish.
6. If you are asked if you want to create a publish container, click OK.
7. Select the job server or job server cluster to monitor the publish container and click Close.
Options for View Layout
284 Contributor
You need the rights to add an application to the job server or job server cluster.
A publish job is queued. You can monitor the progress of the jobs.
In the Publish Options window, you can set the publish options and configure the publish datastore
connection.
Option
Creating a New Publish Container
Configure the Publish Datastore
Connection
Description
The first time you attempt to publish data, you can either
create the default publish container, by clicking Publish, or
create a new publish container (p. 285).
To configure the publish datastore connection, click the
Configure button, see (p. 286).

Option
Do Not Populate Zero/Null/Empty
Data
Publish Only Cells With Writeable
Access
Use Plain Number Formats
Remove all data before publishing
new data
Include User Annotations
Include Audit Annotations
Description
Ensure that empty cells are not populated with zeros.
Selecting this option can substantially speed up the process
of publishing data, depending on the number of blank cells.
Selecting this check box publishes only rows that include
at least one cell with write access; rows for which all cells
are read-only or hidden are not included. Clearing this check
box publishes all cells, including hidden cells, regardless of
access levels.
Selecting this check box removes any numeric formatting
for the purposes of export. It exports to as many decimal
places as are needed, up to the limit stored on the computer.
Negative numbers are prefixed by a minus sign. No thou-
sand separator, percent signs, currency symbols, or other
numeric formats that were applied on the dimension or D-
Cube are used. Plain Number Format uses the decimal point
(.) as the decimal separator.
Selected by default, selecting this option ensures that a
consistent set of data is published. It publishes data for all
the selected cubes, and remove all other published data in
the datastore.
If this check box is cleared, it leaves existing data, unless
the e.List item is being republished. In this case, it removes
the existing data for that e.List item and replace it with the
new data.
Create a Custom Publish Container
Selecting this check box publishes cell level user annotations
in a table named an_cubename.
Publishes audit annotations to a table named an_cubename,
in the column annotation_is_edit.
Before you publish data, no publish containers exist. You can create a custom publish container.
When you create a table-only publish layout (p. 277) or a view publish layout (p. 279), you can also
create a default publish container using default naming conventions on the same datastore server
as the application datastore.
Chapter 15: Publishing Data
Administration Guide 285

Chapter 15: Publishing Data
Type of Publish
Table-only layout
View Layout
Steps
Publish Container Name
applicationname_table
applicationname_view
1. In the Production application, click Publish, and either Table-only Layout or View Layout
depending on the type of publish container you require.
2. Click the Options tab, and then click the Configure button.
3. Select the datastore server where you want the publish container to be created.
4. Click Create New.
5. Click the button next to the Name box .
6. Complete the New publish container dialog box:
● Application name
Type a name for the publish datastore. We recommend that you use the name of the current
application and append to it a suffix, such as, _view for a view layout, or _table for a table-
only layout.
● Location of datastore files
Enter an existing location for the datastore files on the datastore server. Required only by
SQL Server applications.
7. If you have an Oracle and DB2 UDB application, click Tablespace and then specify the following
configuration options:
● Tablespace used for data
● Tablespace used for indexes
● Tablespace used for blobs
Custom temp tablespaces are supported for Oracle only.
8. Click Create.
If you are prompted to create a script, this must be run by a DBA to create the publish container.
If you are not prompted to create a script, the container is created.
The publish container must be added to a job server or job server cluster so that the publish
jobs are processed.
Configure the Datastore Connection
286 Contributor
You must have Modify connection document rights (p. 39) for the datastore server.

You can select and configure the publish container.
Note: Tablespace settings can be configured only when creating a new publish container.
Steps
1. In the Production application, click Publish, and either Table-only Layout or View Layout
depending on the type of publish container you require.
2. Click the Options tab, and then click the Configure button.
If you are prompted to create and generate a script, do the following:
● Click OK and Cancel.
● Click Generate Synchronization Script for Datastore.
● Name and save the script, and pass to the DBA to run the script.
● When the script is run, click the Configure button.
For more information on scripts, see "Publish Scripts" (p. 260).
3. Click the required publish container and click Configure.
4. Configure the following options.
Option
Trusted Connection
Use this account
Password
Preview Connection
Test Connection
Action
Click to use Windows authentication for the logon
method to the datastore. You do not have to specify a
separate logon ID or password. This method is common
for SQL Server datastores and less common, but possible,
for Oracle.
Enter the datastore account that this application will use
to connect. This box is not enabled if you use a trusted
connection.
Type the password for the account. This box is not
enabled if you use a trusted connection.
Click to view a summary of the datastore server connec-
tion details.
Click to check the validity of the connection to the
datastore server. This is mandatory.
5. If you want to configure advanced settings, click Advanced, and enter the following information.
Typically these settings should be left as the default. They may not be supported by all datastore
configurations.
Chapter 15: Publishing Data
Administration Guide 287

Chapter 15: Publishing Data
Setting
Provider Driver
Connection Prefix
Connection Suffix
6. Click OK.
Remove Unused Publish Containers
288 Contributor
Description
Select the appropriate driver for your datastore.
Specify to customize the connection strings for the needs
of the datastore.
Specify to customize the connection strings for the needs
of the datastore.
You can remove unused publish datastore containers. This does not delete the datastore container,
it just removes the reference so that it is not displayed in the Select Publish Datastore Container
window.
Steps
1. From the Tools menu, click Maintenance, Validate Publish Containers. A list of publish con-
tainers is displayed.
2. Select the ones you want to remove, and click Delete.

Chapter 16: Commentary
Attached documents and user annotations that are linked to a plan are grouped together and are
named Commentary. The user can view an attached document by browsing the Commentary of
an application.
The Maintenance branch of the production application enables the user to delete user annotations,
audit annotations, and attach documents from the application datastore. The user can also filter
what to delete based on a date or the text that it contains.
User and Audit Annotations
User annotations can be associated with a cell, cube (or Tab in the Web client), and model. Any
owner of an e.List item with assigned or inherited rights that are greater than View can annotate.
Users with View rights cannot annotate, but can view existing annotations.
Administrators can choose to record user actions, these records are called audit annotations. You
can record user actions in the Web client, such as adding and editing data or importing files.
Tracking changes through the system is useful for auditing purposes and to see who has made
changes if an e.List item has multiple owners.
To control its impact on the size of the application datastore, audit annotations are configured in
Application Options, see "Change Application Options" (p. 74).
Delete Commentary
Administrators can delete comment in a Contributor application using date and time, character
string and e.List item name filters. See "Deleting Commentary" (p. 290) for more information. The
user can also automate the deleting of annotations by using a macro "Delete Commentary" (p. 217).
Users can also delete annotations. See the Contributor Browser User Guide for more information.
Delete Commentary - e.List items
Before you can delete commentary, they must select all the e.List items that they want to delete
them from. To do this, use the buttons at the top of the Delete Annotations, e.List Items tab to:
● Select All or Clear All e.List items.
● Select All Children or Clear All Children.
● Select All Planners or Clear All Planners.
You can also click individual items to select or deselect them.
Administration Guide 289

Chapter 16: Commentary
Deleting Commentary
You can delete all commentary in a Contributor application using date and time, character string
and e.List item name filters.
After you specify the filters, e.List items for the annotations to be deleted, and click Delete comment-
ary, a COMMENTARY_TIDY job is run. The deletion is not seen by web clients until a reconcile
is run. This enables the commentary to be deleted while the Contributor application is online. This
may be run as a macro (p. 217).
Annotations and saved annotations can be deleted by the creator until the annotation is submitted.
Steps
1. In the Production branch of the application, click Maintenance, Delete Commentary.
2. On the Delete options tab, click the options as required:
● Delete user annotations
Note: There are three types of annotations, Note, Note Attachment, and Attachment. Only
the Note type annotation is deleted when this option is selected. Annotations added with
attachments are not deleted.
● Delete audit annotations
● Delete attached documents
● Apply date filter. Select if the user wants to delete commentary by date. If the user selects
this option, they must select a date from the Delete commentaries before date box. It will
default to today's date at midnight, local time.
● Apply annotation content filter. Select if the user wants to delete commentary by content.
For example, if they want to delete annotations containing the word banana, any annotations
containing this word will be deleted, if they also conform to the other filters.
3. Click the e.List items tab and click the e.List items that the annotations will be deleted from.
4. Click Delete Commentary.
The Tidy annotations job runs on available job servers. To monitor the progress of the job,
view the Job Management window (p. 52).
Configuring the Attached Documents Properties
290 Contributor
In the Contributor Administration Console, the administrator designates what type of files are
allowed and also configures the size limits of an attached document. These settings are set at the
System level and apply to all applications within a specific Planning environment.
Note: The maximum number of attached documents is 500.
For more information, see "Configure the Web Client" (p. 71).

Publishing Attached Documents
Information about attached documents can be published using the Table-Only Layout publish
function. Information such as file size, file name, location, and the user who attached the file is
published.
For more information, see "The Table-Only Publish Layout" (p. 265).
Copy Commentary
Attached documents and user annotations that are linked to a plan are grouped together to form
Commentary. The user can copy commentary between Contributor cubes and applications using
administration, system, and local links.
After you run a link that includes commentary, annotation or attached documents, the target will
have the same value and commentary as the source. This means that commentary in the target is
removed if there is no commentary in the source. If you target a cell with more than one source
cell, it will contain the aggregated value and the commentary from all the source cells. If you select
only one type of commentary in the link, then the other type of commentary is not affected by
running the link. You will not have multiple copies of commentary in target cells if you rerun the
link.
Note: The user can only copy Commentary using links that contain data.
For more information, see "Managing Data" (p. 143).
Breakback Considerations when Moving Commentary
Breakback does not occur when attaching commentary either manually or by using an administration
or system link. Commentary can be attached to a calculated cell without impacting cells making
up that calculation.
Note: Identical documents from different sources are treated as separate documents.
Chapter 16: Commentary
Administration Guide 291

Chapter 16: Commentary
292 Contributor

Chapter 17: Previewing the Production Workflow
The Preview window gives you a preview of the production e.List and workflow state and allows
you to view properties of the e.List items. The icons indicate the current status of the data in the
production application. Clicking Refresh enables you to keep track of the status of the icons. For
example, when you have put a development application into production, you can see when e.List
items have been reconciled, see "Reconciliation" (p. 54). In this case, the icons will change from
Not started, out of date to Not started, reconciled .
See "Workflow State Definition" (p. 295) for more information.
To preview the data in the production application in the Preview window, expand the Preview tree,
right-click the e.List item and click Preview.
When you preview an e.List item it appears to behave like it does in the Web. For example, you
can right-click in the grid and click Annotate cell, Add and an annotations window appears. You
can type in the annotations window and when you close the window, you can view the annotation
by moving your mouse over the red square. However, after you have closed the Preview, these
changes are not saved.
Note: Any action you perform in Preview has no bearing on the Production application.
Previewing e.List item Properties
Right-click the e.List item and click Properties. A five-tabbed window is displayed containing:
● General
● Owners
● Editors
● Reviewers
● Rights
Preview Properties - General
The General tab contains the following information:
Property
e.List item type
e.List item state
Description
Indicates whether it is a contribution or a review e.List item.
The workflow state, see "Workflow State Defini-
tion" (p. 295) for more information.
Administration Guide 293

Chapter 17: Previewing the Production Workflow
Property
Date state changed
User who last changed the state
Number of children
Number of locked children
Number of saved children
Preview Properties - Owners
Description
This gives the date and time that the workflow state
changed in the following format: yyyy-mm-dd hh:mm:ss.
The name of the user to have last changed the state.
The number of items in the next level below this e.List item.
The number of child items that are locked, indicating that
data was submitted.
The number of child items where work has started and been
saved.
This Owners tab contains the following information about the owners of the selected e.List item.
Property
Owner name
E-mail address
Current Owner
Preview Properties - Editors
Description
The following information is displayed on this tab.
The name of an owner of the e.List item. An owner is a
user assigned to an e.List item with greater than View rights.
The e-mail address of the user.
This is checked if the owner is the current owner of the
e.List item. The current owner is the last user to have
opened an e.List item for editing.
● Editor - the name of the last or current editor, the time they started editing the e.List, and
whether they are working online or offline.
● Annotator - the name of the last or current annotator, and the time they started creating an
annotation.
For information about editing while offline, see "Working Offline" (p. 89).
Preview Properties - Reviewers
294 Contributor
This lists the reviewers for the e.List item and their e-mail addresses.
The Data Reviewed indicator indicates whether the e.List item was reviewed and the Data Viewed
indicator indicates whether the data was viewed or not.

Preview Properties - Rights
This displays the following information:
Property
e.List item Display Name
User, Group, Role
Rights
Inherit from
Description
The e.List item display name.
The User, Group, or Role assigned to the e.List item (more
than one user, group, or role can be assigned to an e.List
item).
The level of rights that a user has to the e.List item.
If the rights have been directly assigned to the user, this cell
will be blank. If the rights have been inherited, this indicates
the name of the e.List item the rights have been inherited
from.
You can print this information, or save it to file.
Workflow State Definition
The workflow state icons indicate the state of data in the IBM Cognos 8 Planning - Contributor
application.
Icon
State
Not started
Work in pro-
gress
Incomplete
Ready
Contribution
The e.List item has not been edited
and saved (it may have been edited
but the changes not saved).
The e.List item was edited and
saved but not submitted.
Not applicable.
Not applicable.
Chapter 17: Previewing the Production Workflow
Review
None of the items that make up this
e.List item have been edited and
saved.
All items that make up this e.List
item have been edited and saved. At
least one item has not yet been sub-
mitted.
Some items that make up this e.List
item have not been started. At least
one item was started.
All items that make up this e.List
item have been submitted and are
locked. This item can be submitted
for review.
Administration Guide 295

Chapter 17: Previewing the Production Workflow
Icon
State
Locked
Additional Workflow States
Contribution
The e.List item was submitted and
can no longer be edited.
Review
The e.List item was submitted.
In addition to these workflow states, there are additional icons that indicate variations on these
states. The variations are:
Icon
Variation
Has a current editor/annotator.
Is out of date.
Has a current editor/annotator and
is out of date.
Description
The e.List item was opened for
editing/annotating. An edit session is ended by
the user closing the grid, or by submitting the
e.List item.
This indicates that the e.List item needs recon-
ciling. This happens when Go to Production
was run on the application and the e.List item
has not been reconciled. If client side reconcili-
ation is prevented, the user is unable to view
the data until reconciliation has occurred.
There is a current editor or annotator, and the
data is out of date.
These additional states only appear to the user in the front window of the Contributor application,
not in the grid.
Workflow State Explained
296 Contributor
This diagram demonstrates the different workflow states that in Contributor.

Each icon represents the state of the e.List item. The lowest level e.List items (for example, labeled
A1 Profit Center) are contribution e.List items, that is items that you enter data into. The higher
level e.List items are review e.List items, and the state of a review e.List item is affected by the states
of the contribution e.List items that feed into it.
States for Contribution e.List Items
Before data is entered and saved in an e.List item, its state is Not started. After you save an e.List
item, the state becomes Work in progress and remains accessible for more editing. When you submit
an item, the e.List item is Locked and no more changes can be made. The Locked state indicates
that the e.List item is ready for review. A reviewer can review the e.List item in any state, but can
only reject a Locked e.List item. When an e.List item is rejected, it returns to a state of Work in
progress.
States for Review e.List Items
A review e.List item where none of the items that feed into it have been saved has a state of Not
started (see A Region). When at least one of the items that make up a review e.List item is not saved,
and at least one other item is saved, its state is Incomplete (see Total Company, Division X and B
Region). When all the items that make up a review e.List item are saved and at least one is not
submitted, its state is Work in progress (see Division Y and C Region).
After all the e.List items that make up a review e.List item are locked, the state of the review e.List
item is Ready (see D Region) and if acceptable, can be submitted to the next reviewer. After it is
submitted, it becomes Locked (E Region).
Chapter 17: Previewing the Production Workflow
Administration Guide 297

Chapter 17: Previewing the Production Workflow
Other Icons
298 Contributor
Each of the Workflow state icons can have additional indicators that tell you whether the e.List
item is being edited, is out of date, or both. They are a grid, a box or both a grid and a box.
The following show examples of these indicators, but note that they can apply to all workflow
states:
● Has a current editor/annotator. The e.List item was opened for editing/annotating. An edit
session is ended by the user closing the grid, or by submitting the e.List item .
● Is out of date . This indicates that the e.List item needs updating.
● Has a current editor/annotator and the data is out of date.

Chapter 18: Using Contributor With Other IBM
Cognos Products
Client and admin extensions help Contributor to work with other IBM Cognos products (p. 300).
You can analyze and report on published Contributor data in IBM Cognos 8 Business Intelligence
using the Generate Framework Manager Model admin extension (p. 306). Additionally, the Planning
Data Service provides access to unpublished Contributor data for IBM Cognos 8 Business Intelligence
users.
You can use Excel with Contributor, benefiting from the formatting capabilities of Excel (p. 311).
You can take actuals from an Enterprise Resource Planning (ERP) system and combine them with
planning information to perform comparative analysis using IBM Cognos Performance Applications
(p. 312).
You can also manage Contributor master dimensions with IBM Cognos 8 Business Viewpoint Client
(p. 314).
The following diagram illustrates some of the integration points between Planning and other IBM
Cognos products.
Published Data
Real Time Data
IBM Cognos Connection
Performance
Applications
IBM Cognos 8
Business Intelligence
Planning OLAP Relational
IBM Cognos 8
Business Intelligence
Transformer 7.4
IBM Cognos 8
Planning - Contributor
IBM Cognos 8
Controller
IBM Cognos 8
Metrics Manager
IBM Cognos 8
Planning - Analyst
IBM Cognos
Finance
Administration Guide 299

Chapter 18: Using Contributor With Other IBM Cognos Products
Client and Admin Extensions
Extensions are tools that provide additional functionality to Contributor as well as provide inter
operability with other IBM Cognos products. There are two types of extensions:
● "Classic Client Extensions" (p. 300)
● "Admin Extensions" (p. 301)
All extensions are installed as part of the main Planning installation. For more information, see the
IBM Cognos 8 Planning Installation Guide.
Note: Ensure that both the Administration Console computer and the client computers meet all of
the software and hardware requirements before configuring and running Contributor client and
administration extensions.
For a current list of the software environments supported by IBM Cognos products, see the IBM
Cognos Resource Center Web site (http://www.ibm.com/software/data/support/cognos_crc.html).
Classic Client Extensions
Classic web client users can use client extensions to take advantage of the functionality of Excel
(p. 311). The Contributor Web Client includes the Get Data and Export for Excel functionality.
Client extensions are activated through the menu bar in the Contributor grid.
You can control when an extension is available for Classic Contributor Web Client users by enabling
and disabling it in Contributor Administration Console. Get Data and Excel functionality is always
available to Contributor web client users.
Tip: For Classic Contributor Users, on the Configure Extensions tab, right-click the extension and
click Enable or Disable.
Organize Classic Client Extensions
300 Contributor
Use extension groups to organize client extensions. Extension groups appear as items under the
Tools menu on the Classic Contributor grid. A list of the member extensions appear when you click
the group name. For example, you can create an extension group named Export to organize the
export extensions.
Steps
1. In the Contributor Administration Console application tree, click Production, Extensions, Client
Extensions, and then click the Extension Groups tab.
2. Click Add, and type a name for the new group.
Extension group names must be 15 characters or less and should be meaningful to the Web
client user.
3. Click OK.
The name of the new extension group appears in the Extension Group list.
Tips:
● You can rename an extension group by clicking Edit in the Extension Group dialog box.

Configure Classic Client Extensions
● You can reorder extension groups by using the arrow buttons on the Extension Group tab.
You must configure a client extension before users can use it. An extension can run in the Classic
web client in a custom or manual mode. In manual mode, extensions run when a user selects the
extension from the Extension Group list under the Tools menu in the Classic web client. In custom
mode, extensions run automatically in the Classic web client and do not need to be assigned to an
extension group.
Tip: You can reset a client extension back to its original settings by clicking the Reset button. This
resets the configuration back to its original, unconfigured state and all settings and data are lost.
Steps
1. In the Contributor Administration Console application tree, click Production, Extensions, Client
Extensions, and then click the Configure Extensions tab.
2. Click the extension you want, and click Configure.
The Extension Properties dialog box appears.
3. In the Display Name box, type a name for the extension or leave the default name.
4. If the Activation Mode box shows that Manual activation mode is selected, in the Extension
Group box, click the appropriate Extension Group.
5. In the Extension Properties-Users dialog box, click All Users or Selected Users.
6. If you clicked Selected Users, select the check box next to each user who should have access.
7. If you are configuring the Export for Excel extension, in the Location on client for saved
selections box, type the full path of the saved selections folder.
Note: If you are using Windows Vista, you will need administrative privileges to save a saved
selection to the root directory (c:\). If you do not have administrative privileges, then specify a
different path, for example c:\your folder\saved_selection_name.sav.
8. Choose whether to enable this extension now by clicking Yes or No.
9. Click Finish.
Admin Extensions
Run an Admin Extension
Administrators use admin extensions to generate Framework Manager models, Transformer
Models, and IBM Cognos PowerCubes from Contributor applications. This enables you to report
on Contributor data in IBM Cognos 8 studios, and view data in PowerPlay Series 7.
You run an Admin extension when you want it to perform its task. Before you can run an Admin
extension, you must first configure it. For information about configuring the individual extensions,
see the following topics:
Chapter 18: Using Contributor With Other IBM Cognos Products
Administration Guide 301

Chapter 18: Using Contributor With Other IBM Cognos Products
● "The Generate Framework Manager Model Admin Extension" (p. 306)
● "Generate Transformer Model" (p. 309)
Step
● In the Contributor Administration Console application tree, click Production, Extensions,
Admin Extensions, select the extension, and click Run.
You may be prompted to perform more tasks, depending on the extension.
Integrating with IBM Cognos Business Intelligence Products
IBM Cognos Business Intelligence (BI) users can access unpublished (real-time) and published
Contributor data for analysis and reporting.
For IBM Cognos 8 Business Intelligence users, the Planning Data Service provides access to
unpublished Contributor data, and the Generate Framework Manager Model extension provides
access to (table-only layout) published data. Note that you get better performance when reporting
off published data than off live data. This is because the Planning Data Service has the added
overhead of interpreting the model.
You can also import data from IBM Cognos 8 data sources into Contributor applications and
Analyst models. For more information, see "Importing Data from IBM Cognos 8 Data
Sources" (p. 164).
Using IBM Cognos 8 BI with Contributor Unpublished (Real-Time) Data
302 Contributor
You can use IBM Cognos 8 Business Intelligence to report on and analyze unpublished (real-time)
Contributor data.
To create a Planning Package, you have two options.
● Select the Create Planning Package option in the Go to Production wizard
● Create a package directly in Framework Manager
To determine which method to choose consider the following information.
Create the Planning Package in the Go to Production Wizard
The Planning Package that is published in the Go to Production wizard contains all cubes in the
application. Thus, when a user opens this package in Query Studio, Analysis Studio, Report Studio,
or Event Studio, they are presented with metadata for all of the cubes in the application. The user
is free to choose metadata from multiple cubes for use in their reports. However, unless care is
taken, users may inadvertently build queries that attempt to access values from more than one cube,
which results in no data returned to the report.
For more information, see "Planning Packages" (p. 244).
Create the Planning Package Directly in Framework Manager
If you create the package in Framework Manager, you can determine how many cubes to expose
in a given package. By default, you get one cube in each package, which prevents users from

Framework Manager Project
building queries that access more than one cube. However, this may result in large numbers of
packages in IBM Cognos Connection which could be difficult to manage.
Before you can create a package using Framework Manager, you must create a Framework Manager
project. The Framework Manager project contains objects that you organize for Business Intelligence
authors according to the business model and business rules of your organization. A package is a
subset of the query subjects and other objects defined in the project.
Framework Manager can use the metadata and data from external data sources to build a project.
To import metadata, you must indicate which sources you want and where they are located. You
then publish the package to the IBM Cognos 8 server so that the authors can use the metadata.
You can create several packages from the same project, with each package meeting different
reporting requirements. Framework Manager models accessing Contributor data are light-weight
models only. A light-weight model, as well as the packages derived from that model, contain only
the connection information to the cubes in the Planning application. The D-List and item metadata
are extracted from the Planning application at runtime.
Note: Cross tab reports in any of the Business Intelligence studios do not support text or date-based
measures, including annotations, if configured for display. If a text or date-based measure is selected,
it appears as "--" in the report.
The Measures Dimension
IBM Cognos 8 requires that one of the Contributor D-Lists is used as the measures dimension. A
measures dimension is typically one that contains quantitative data items, such as revenue or
headcount. The default measures dimension is determined based on the following:
● Excluding the e.List, all dimensions with defined formats.
● Other than the e.List, if no dimensions have defined formats, then the first dimension is used.
● If only one dimension has defined formats, that dimension is used.
● If more than one dimension has defined formats, the dimension with the lowest priority calcu-
lations is used.
The default measures dimension can be overridden when publishing, by selecting the Dimension in
the Cubes screen. If you republish the data and change the dimension at a later date, be aware that
this may break some saved reports.
Create a Framework Manager Project and Publish a Package
The Framework Manager project contains objects that you organize for Business Intelligence authors
according to the business model and business rules of your organization.
Steps
Chapter 18: Using Contributor With Other IBM Cognos Products
1. From the Windows Start menu, click Programs, IBM Cognos 8, Framework Manager.
2. In the Framework Manager Welcome page, click Create a new project.
3. In the New Project page, specify a name and location for the project.
Administration Guide 303

Chapter 18: Using Contributor With Other IBM Cognos Products
304 Contributor
4. Optionally, you can add the new project to a source control repository by doing the following:
● Click Repository, and then select the Add to repository check box.
● In the Connection box, click the repository connection.
If you do not have a repository connection defined, you are prompted to create one. For
more information, see the Framework Manager help.
● In the Location in Repository box, browse to a location to add the project and then click
Select.
5. Log on if you are prompted to do so.
6. In the Select Language page, click the design language for the project.
You cannot change the language after you click OK, but you can add other languages.
7. In the metadata source page, select Data Sources.
8. If the data source connection you want is not listed, you must create it (p. 305).
If the Planning Data Service is configured, a data source named IBM Cognos Planning - Con-
tributor is available. This gives you access to cube (OLAP) data only. If you want to access
table data, you must create a data source that points to these tables.
9. Select the cube that you want to import.
The name of the project is shown. This defaults to the cube name. You can change this.
10. Add security to the package if required. See the IBM Cognos 8 Framework Manager User Guide
for more information.
11. Click Next and then Finish.
Note: You save the project file (.cpf) and all related XML files in a single folder. When you
save a project with a different name or format, ensure that you save the project in a separate
folder.
12. When prompted to open the Publish Wizard, click Yes. This enables you to publish the new
package to IBM Cognos Connection.
13. In the Publish Wizard, choose where to publish the package:
● To publish the package to the IBM Cognos 8 Server for report authors and business authors
to use, click IBM Cognos 8 Content Store.
● To publish the package to a network location, click Location on the network.
14. To enable model versioning when publishing to the IBM Cognos 8 Content Store, select the
Enable model versioning check box.
15. In the Number of model versions to retain box, select the number of model versions of the
package to retain.
Tip: To delete all but the most recently published version on the server, select the Delete all
previous model versions check box.

16. If you want to externalize query subjects, select the Generate the files for externalized query
subjects check box.
17. By default, the package is verified for errors before it is published. If you do not want to verify
your model prior to publishing, clear the Verify the package before publishing check box.
18. Click Publish.
If you chose to externalize query subjects, Framework Manager lists the files that were created.
19. Click Finish.
Create a Data Source Connection
Note: You can run the Framework Manager Metadata wizard repeatedly to import multiple
cubes into the same Framework Manager project. For more information about creating
Framework Manager projects, see the Framework Manager User Guide.
You must create a data source connection if you are creating a Planning Package in Framework
Manager.
When you create an IBM Cognos 8 Planning - Contributor data source, you must provide the
information required to connect to the datastore. This information is provided in the form of a
connection string.
Data sources are stored in the Cognos namespace and must have unique names. For example, you
cannot use the same name for a data source and a group.
Before creating data sources, you need write permissions to the folder where you want to save the
data source and to the IBM Cognos namespace. You must also have execute permissions for the
Administration secured function.
Steps
1. In Framework Manager, click the Run Metadata Wizard command from the Action menu.
2. Click Data Sources and Next.
3. Click New and Next.
4. In the name and description page, type a unique name for the data source and, if you want, a
description and screen tip. Select the folder where you want to save it.
5. In the connection page, under Type, click IBM Cognos Planning - Contributor.
The connection string page for the selected database appears.
6. Under External namespace, select the namespace set up previously in IBM Cognos Configuration.
Tip: To test whether parameters are correct, click Test the connection. If prompted, type a user
ID and password or select a signon, and click OK.
7. Click Finish.
The data source appears in the Directory tool in the portal or in the list of data sources in the
Metadata Wizard in Framework Manager.
Chapter 18: Using Contributor With Other IBM Cognos Products
Administration Guide 305

Chapter 18: Using Contributor With Other IBM Cognos Products
Tip: To test a data source connection, right-click the data source in the Data Sources folder and
click Test Data Source.
The Generate Framework Manager Model Admin Extension
Generate Framework Manager Model creates a set of Framework Manager models from IBM
Cognos Planning data published in a table-only layout, including a base model and a user model.
It also publishes a package to IBM Cognos Connection.
Base Model
The base model contains the definitions of objects required to access IBM Cognos Planning data
published in a table-only layout. The objects include table definitions (query subjects), dimension
information, security filters, and model query subjects.
User Model
The user model provides a buffer to contain the modifications made by the Framework Manager
modeler. When modifications are made to the Contributor application, or to the Analyst model,
the base model can be updated using Generate Framework Manager Model. Then, the user model
can be synchronized using the synchronize option in Framework Manager.
The synchronization process makes all the modifications to the base model appear in the user model.
This is done by synchronizing the user model with the base model and by reapplying any changes
made to the user model by the modeler to the synchronized user model.
The package published to IBM Cognos Connection is published from the User Model.
Configuring Your Environment
306 Contributor
Before you can use Generate Framework Manager Model, you must configure your environment.
Do the following:
Note: It is recommended that you install the Administration components (Analyst and Contributor
Administration Console) on the same machine as the Planning Server components.
❑ Ensure that you can access IBM Cognos Connection
For example, in the address bar of your Web browser, type http://computer_name/cognos8/.
❑ Ensure that you can publish the IBM Cognos Planning data in a table-only layout.
❑ Configure the Publish datastore to use the logon and password of the datastore server, not
Trusted Connection.
Understanding Generate Framework Manager Model
When you generate a Framework Manager model, the following occurs:
● An IBM Cognos 8 data source is created for the Table-only publish container.
● The Framework Manager script player
● creates models and packages object actions from the Table-only publish metadata
● publishes packages

Objects in the Generated Framework Manager Model
The models generated by Generate Framework Manager Model contain the following objects.
Folders
Framework Manager contains a series of folders containing objects of the same type. These folders
are created in two top-level folders: Physical View and Business View. The Physical View Folder
contains all the database query subjects and the Business View folder contains all the dimension
and star schema objects.
Database Query Subjects
Database query subjects are created for all the tables needed to provide access to IBM Cognos
Planning data. The tables included in the model depend on the query subjects selected, and may
include
● cube export tables
● dimension item tables
● dimension derived hierarchy tables
● dimension complete hierarchy tables
● annotation tables
Joins
Joins are created between related tables, such as the cube export data tables and derived hierarchy
tables.
Column Usage
The usage attribute of the query items contained in the database query subjects are set to the correct
value: fact, identifier, or attribute.
Security Filters
If the models are generated from a Contributor application, security filters are created for each cube
export data query subject. The filters grant users access to the same e.List items as in the Contributor
application. A security filter is created for every user on every cube export data query subject.
If the models are generated from Analyst, no security filters are created.
Regular Dimensions
For each derived hierarchy and complete hierarchy query subject, a regular dimension object is
created and saved to the Derived Dimensions and Complete Dimensions folders respectively. These
folders are located in the Business View folder.
Measure Dimensions
Chapter 18: Using Contributor With Other IBM Cognos Products
For each cube export table, a measure dimension object is created. It is stored in a folder that has
the same name as the cube. These folders are located in the Business View folder.
Administration Guide 307

Chapter 18: Using Contributor With Other IBM Cognos Products
Star Schema Groupings
For each cube in the model, some star schema groupings are created. If the derived hierarchy lists
are selected, a star schema grouping is created using the derived dimensions. If the complete hierarchy
lists are selected, a star schema grouping is created using the Complete Dimensions folders.
Data Source
Data source refers to the data source created in the IBM Cognos Connection Portal.
Package
A package contains all the objects in the Framework Manager model. The administrator of the
package is the user generating the model.
In Contributor, the users who have access to the package are the users of the Contributor application.
In Analyst, the only user to have access to the package is the user generating the model.
Objects Created in IBM Cognos Connection
When generating a Framework Manager model using Generate Framework Manager Model, a data
source is added to IBM Cognos Connection. The associated connection string and signon is also
created if applicable.
Run the Generate Framework Manager Model Admin Extension
308 Contributor
Run the Generate Framework Manager Model Admin Extension to create a set of Framework
Manager models from IBM Cognos 8 Planning data.
This extension cannot be automated.
In the appropriate Contributor application, publish data using the Table-only layout. You must
use an untrusted connection.
Note: This extension uses the last published container.
Steps
1. Click Extensions, Admin Extensions, and double-click Generate Framework Manager Model.
2. Select Create a new Framework Manager Model and click Next.
3. Specify the following Framework Manager Model settings:
● Framework Manager Model Location
Where the Base model and User model are created on the hard disk. Only one model can
exist in any location.
● Package name
The name of the package to be published to the portal. The Package name must not already
exist on the portal.
● Package location
Where the package is stored in IBM Cognos Connection.

● Package screentip
● Package description
4. Select the cubes to be included in the model.
5. Specify the type of data source query subjects to include in the model.
When the package is published, it can be accessed from IBM Cognos 8 studios.
The selections made in this extension are saved for the next time the extension is run and are used
when updating a model.
For troubleshooting information, see "Troubleshooting the Generate Framework Manager Model
Extension" (p. 361).
Update a Framework Manager Model
You can update a Framework Manager model to include changes to the Contributor application.
The new base model is re-imported and any changes you made to the user model are reapplied.
Steps
1. In the appropriate Contributor application, click Extensions, Admin Extensions, and double-
click Generate Framework Manager Model.
2. In Create or update model, select Update an existing Framework Manager Model.
3. Enter the Project Location where the model you want to update is stored.
4. Complete the steps in the wizard.
5. Open Framework Manager and open the User Model.
6. From the Project menu, click Synchronize and then click Run the script from the starting point.
Generate Transformer Model
Use the Generate Transformer Model to generate an IBM Cognos Transformer Model from a table-
only database layout and create IBM Cognos PowerCubes. You can view the PowerCube in
PowerPlay Series 7, or publish the PowerCube to a package in IBM Cognos Connection and view
its content using any of the IBM Cognos 8 studios.
Because the PowerCube is based on published data, the Generate Transformer Model extension
generates a single Transformer model for each Contributor model. The extension automatically
extracts the necessary information about your Contributor model from the publish tables and the
application model, and then creates the equivalent model in Transformer. After the Transformer
model is created, you can modify it using the Transformer interface and optionally, publish the
cubes to an IBM Cognos Portal. Generate Transformer Model uses the last publish data source.
With the Generate Transformer Model, you can:
● generate a Transformer model
Chapter 18: Using Contributor With Other IBM Cognos Products
Administration Guide 309

Chapter 18: Using Contributor With Other IBM Cognos Products
310 Contributor
● generate a Transformer model and a PowerCube. Transformer must be installed to generate a
PowerCube
● create a PowerCube from an existing Transformer model
Before you can use the Generate Transformer Model Wizard, you must configure your environment.
Do the following:
● If you create PowerCube(s), ensure that you can access IBM Cognos Connection.
For example, in the address bar of your Web browser, type http://computer_name/cognos8/.
● Publish your IBM Cognos 8 Planning data in a table-only layout.
● Before you can create PowerCube(s), you must first have Transformer installed and configured
on the computer where the Planning Server components are installed.
Security Considerations
The Transformer model and PowerCubes generated can only be secured against a Series 7 Namespace.
The name of the namespace in IBM Cognos Configuration must match the name of the Series 7
namespace.
We recommend that the user class for the administrator creating the Transformer model has the
property: Members can view all users and/or user classes in the User Class permissions tab. This
property is set in the administration console of Access Manager Series 7.
Automation
This extension can be automated. It must first be configured. For more information, see "Execute
an Admin Extension " (p. 218).
Steps
1. In the Contributor Administration Console application tree, click Production, Extensions,
Admin Extensions and double-click the Generate Transformer Model extension.
2. Choose whether to generate a Transformer model, and a PowerCube, or just a PowerCube.
3. Specify the location and file name for the Transformer model and the location for the Power-
Cube.
This location can contain only one model. The paths must be located on the Planning server,
and can be UNC paths.
4. You can choose to include security information. To do this you must specify a Series 7
Namespace.
5. Choose the cubes to add to the Transformer model.
6. If you selected Create PowerCube, you can choose to create a Planning Package, enabling you
to view its content using any of the IBM Cognos 8 studios.
7. Click Finish.

Excel and Contributor
In addition to accessing Contributor through the Web, users can access Contributor using Contrib-
utor for Excel. This enables users to apply Excel formatting and export data from Contributor to
an Excel file.
Design Considerations When Using Contributor for Excel
Because of the formatting and other capabilities of Contributor for Excel, cubes with large two-
dimensional window footprints tend to reduce performance. The two-dimensional window footprint
is not related to e.List model size, which is the total number of cells in an application (per e.List
slice). A two-dimensional window footprint is the number of rows in a cube multiplied by the
number of columns that can currently be viewed on a worksheet.
Performance is affected by the size and complexity of Contributor e.List models. Larger and more
complicated models take longer to download than smaller models. Contributor for Excel does not
impose any new limits on size and complexity.
The performance of Contributor for Excel is also affected by cubes containing large numbers of
Contributor cells visible on worksheets at one time. The following actions are affected:
● breakback
● entering a value
● changing multi-dimensional pages
● saving the model
As a result, you may want to use the most relevant data and not all possible data. There are several
ways to limit the two-dimensional window footprints of cubes. You can design compact, multidi-
mensional cubes. If the model requires a long D-List, consider using access tables to send only the
items needed to different e.List items. Finally, consider using cut-down models as another way of
restricting portions of long D-Lists to some e.List items.
Percentages and Consistency When Using Contributor for Excel
Percentages are usually numbers between 0.00 and 1.00. Contributor permits a cell, with a value
not between 0.00 and 1.00 to appear as a percentage by appending the percent (%) character.
Model calculations then divide such a number by 100 to convert it to a percent.
Contributor for Excel initially matches these formatting conventions, including the trailing %
character as custom Excel formatting. However, if users reformat such cells, the true underlying
value can be revealed and may be confusing. For example, reformatting a 5% increase as Genera
shows the underlying value as 5.00 or 0.05.
Excel accepts several forms of input in a cell with a % format. It converts user input of 8.00, 0.08,
and 8% to a value of .08 and presents it as 8%. To eliminate possible confusion in your Contributor
model, build models in which values are used as consistently as possible in calculations, display,
and input.
Chapter 18: Using Contributor With Other IBM Cognos Products
Administration Guide 311

Chapter 18: Using Contributor With Other IBM Cognos Products
Specifying the Level of Granularity When Using Contributor for Excel
Some cubes exist so that users can retain more granular data than is actually required for the cent-
ralized planning process.
To improve performance, you may want to remove these cubes and do one of the following:
● Build Excel-based templates that replace such cubes with Excel worksheets linked to Contributor
cells.
● Permit users to decide their own level of granularity and build their own incoming formulas.
Print to Excel for Classic Contributor Web Client
Classic Contributor Web Client users can print data using the print formatting options available
from Excel. Using the Print to Excel functionality is the default standard for the Classic Web Client.
The Activation Mode is set to custom. If the Classic Web Client does not have Excel installed, the
standard print capability is provided.
To configure the Print to Excel extension, see "Configure Classic Client Extensions" (p. 301).
Export for Excel for Classic Contributor Web Client
Classic Contributor Web Client users can use Export for Excel to export data from Contributor to
a Excel file. From there, they can use the Excel formatting and graphing features. Classic Web Client
Users must have the Export for Excel extension enabled.
Web client users can specify a selection of their data to be used for a future export. Saved selections
define specific Contributor data sets to be exported. The Contributor administrator must designate
this location for Classic Contributor Web Client Users.
Note: If you are using Windows Vista, you will need administrative privileges to save a saved
selection to the root directory (c:\). If you do not have administrative privileges, then specify a
different path, for example c:\your folder\saved_selection_name.sav.
We recommend that the Contributor administrator consult with their network administrator to
determine the best location for the saved selections folder.
If the designated folder location does not already exist on the user's computer or on the network,
it is created the first time the user creates a selection. If the designated folder is on a network, advise
users to give their selections unique names so they do not overwrite other saved selections with the
same name. Users are warned prior to overwriting a selection. If you choose not to designate a
folder, you can export data but cannot save the selection information for a future export.
To configure the Export for Excel extension, see "Configure Classic Client Extensions" (p. 301).
Financial Planning with IBM Cognos Performance Applications
and Planning
312 Contributor
You can use IBM Cognos Planning and IBM Cognos Performance Applications together to

● extract actuals from the data warehouse of an Enterprise Resource Planning (ERP) system and
bring them into IBM Cognos Planning, as structural data for the Analyst model and as the
initial figures from the previous planning cycle for Contributor
● return completed planning data to the data warehouse using an ETL tool such as Data Manager
for comparative analysis
● monitor live or published planning data during the planning cycle against current operational
data in the Performance Applications warehouse
The data warehouse extracts, and changes that occur during the planning cycle, are managed using
the Import from IQD wizard. Monitoring is done directly against Contributor data using the
appropriate extensions.
Financial Planning involves the following process:
❑ Preparing IBM Cognos Performance Applications Data for Planning
In the Performance Application, identify the key performance indicators (KPIs) to plan by,
monitor, and report on. Because planning is often performed at a different level from actuals,
you may need to add to the dimensions from the data warehouse. IBM Cognos consultants can
help you in this identification and analysis.
The Import from IQD wizard expects each dimension to have both an ID field and a description
field, each of which must be unique across the dimension.
❑ Preparing for the Model in Analyst
After the planning measures and dimensions that are available from IBM Cognos Performance
Applications have been identified, the Analyst user designs a model, and identifies any alternate
data sources that are needed for the dimensions and measures. Because Performance Applications
use multiple currencies for reporting, the Analyst user should determine what currency to use
when data is published back into the Performance Applications warehouse.
Note: If you create a D-List using the Import from IQD wizard, you should not add any items
manually. If you do add items manually, these items will be removed every time you refresh
the D-List.
After planning models are designed and sourcing is identified, the solution to integrate the
actuals information with planning information can be implemented using either the mapping
table that is generated during the IQD import, or if the mapping tables are not required, you
can use an IBM Cognos package as a source to populate D-Lists in Analyst.
❑ Preparing e.Lists for Contributor Data
As well as importing D-List data for the Analyst model, you can choose to generate e.Lists
using data from IQD files, or if the data is modeled in Framework Manager and published as
a package, you can also use Contributor Administration Links.
For more information about financial planning with IBM Cognos performance applications and
Planning, see the Analyst User Guide.
Chapter 18: Using Contributor With Other IBM Cognos Products
Administration Guide 313

Chapter 18: Using Contributor With Other IBM Cognos Products
Managing Contributor Master Dimensions with IBM Cognos 8
Business Viewpoint Client
With Business Viewpoint Client, you can nominate master dimensions from Contributor into IBM
Cognos 8 Business Viewpoint Studio, which is a master dimension repository. When you nominate
a Contributor dimension, you can also choose to move over e.Lists, any rights, and access tables
in that dimension.
You can also subscribe to a master dimension from Contributor, which is creating a link between
an e.List in the Contributor Administration Console and the master e.List data in Business Viewpoint
Studio.
When you subscribe to a master dimension from Contributor, a copy of the master dimension from
Business Viewpoint Studio is moved to Contributor. If the master dimension is modified in either
of these locations, the data will no longer be synchronized. To ensure that you have the same data
in both places, you can run an update.
You can also include a security model for the items for which you are subscribing, which lets you
create or update the Contributor security to reflect the security model in Business Viewpoint Studio.
For information on how to use the Business Viewpoint Client with C0ntributor, see the IBM Cognos
8 Business Viewpoint Client User Guide. You can access it after you launch Business Viewpoint
Client.
Launching Business Viewpoint Client from Contributor
314 Contributor
You launch Business Viewpoint Client from Contributor, and then perform all master dimension
management actions from within Business Viewpoint Client.
Steps
1. From the Contributor Administration Console Tools menu, click Business Viewpoint Client.
Note: Business Viewpoint Client is the default menu name. You can change the name by editing
the string in the XML file.
2. Log into Business Viewpoint Client.

Chapter 19: Example of Using IBM Cognos 8
Planning with Other IBM Cognos Products
IBM Cognos 8 Planning integrates with all other IBM Cognos 8 Business Intelligence products. For
example, you can create reports on planning data and you can create macros with administration
links that are triggered by events in planning data.
The examples in this section use the Great Outdoors New Stores sample available on the IBM
Cognos Resource Center Web site http://www.ibm.com/software/data/support/cognos_crc.html.
The items created in this example, including the report, event, and PowerCube are included with
the sample download for your reference.
Before downloading and deploying the sample, you will need to install the Sun One Directory Server
(downloaded from the Sun One site), create an instance of a directory server, and then import the
contributor_sample.ldif file located in your Cognos directory, for example: \
samples\Planning\Contributor\en\Data.
To create the application, you will also need to download the e.List and rights from the Document-
ation page on http://www.ibm.com/software/data/support/cognos_crc.html.
Download and Deploy the Sample
The example requires the Great Outdoors New Stores Sample, including a Planning deployment
archive and an IBM Cognos 8 deployment archive. The sample is available from the IBM Cognos
Resource Center and must be imported using the IBM Cognos 8 and Planning deployment wizards.
Steps to Download the New Stores Sample:
1. Download, from the Documentation page on http://www.ibm.com/software/data/support/
cognos_crc.html, the Great Outdoors New Stores Sample (go_new_stores_sample_en.zip).
Tip: Search the IBM Cognos Resource Center Web Site for the document type Utility.
2. Save the files go_new_stores_contributor_data.zip and Cognos8_new_stores.zip to the
deployment location set in IBM Cognos Configuration.
Tip: The default location is C:\Program Files\cognos\c8\deployment.
3. In the deployment location, open the compressed go_new_stores_contributor_data.zip file. The
IBM Cognos 8 deployment archive (Cognos8_new_stores.zip) must remain a compressed file.
4. Save PowerCube.zip to \samples\Planning\Contributor\en\Data\Data_go_new_
stores_contributor. Open the compressed file.
Tip: The default location for the samples folder is C:\Program Files\cognos\c8\samples.
Administration Guide 315

Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
Note: Ensure you import the new_stores_rights.txt file.
Steps to Deploy IBM Cognos 8 Package
1. In IBM Cognos Administration, import Cognos8_new_stores.zip from the deployment archive.
Tip: On the Configuration tab, click Content Administration and select New Import .
2. Complete the Import wizard to import the package and data source connection.
3. On the Configuration tab, click Data Source Connections, select the properties for the new
data source connection, new_stores_power_cube, and update the location of the PowerCube
on the Connection tab to \samples\Planning\Contributor\en\Data\Data_go_
new_stores_contributor\store_cost.mdc.
Note: If you do not save the store_cost.mdc PowerCube to C:\Program Files\cognos\c8\samples\
Planning\Contributor\en\Data\Data_go_new_stores_contributor\, then you will have to
reestablish the Administration link to this data source.
Need more help?
● See the Deployment section in the IBM Cognos 8 Administration and Security Guide
Steps to Deploy the Planning Application
1. Import the go_new_stores_contributor application sample into the Contributor Administration
Console using the deployment wizard.
Tip: Click Tools, Refresh Console after the deployment to display the application, administration
link, and macro.
2. Add the go_new_stores_contributor application to a job server cluster.
3. If you saved the store_cost.mdc Powercube to a location other than the default location, edit
the Administration link data source and target application to map to the data source, new_
stores_power_cube, and the imported planning application, go_new_stores_contributor.
Tip: You do not change the mappings in the administration link.
Need more help?
● "Import a Model" (p. 170)
● "Add Applications and Other Objects to a Job Server Cluster" (p. 57)
● "Create an Administration Link" (p. 149)
Example of Integration with IBM Cognos 8 Business Intelligence
316 Contributor
The example in this section shows you some of the ways that IBM Cognos 8 Planning works with
IBM Cognos 8 Business Intelligence. It demonstrates just a few of the many ways that you can view
and use your planning data.

The Central Europe region of the Great Outdoors Corporation plans to increase sales in its new
stores by holding promotions. The regional manager, Sébastien Pascal, wants a report delivered to
him the first day of every month that shows the current Central Europe promotions plans compared
to projected costs for the promotions and average monthly store revenue.
To complete this task, you need to create a report on the contributions for Central Europe and use
that report in an event that delivers a scheduled news item to Sébastien Pascal. You require IBM
Cognos 8 Business Intelligence products: Framework Manager, Report Studio, and Event Studio.
Run a Contributor Macro to Import Data
A Contributor macro, Import Average Monthly Revenue, that imports the average monthly revenue
for the stores from a PowerCube and completes go to production for the application, has been
created and published to IBM Cognos Connection.
The historical average monthly revenue for Great Outdoors stores is stored in a PowerCube. The
Administration link in this macro moves the data from a Framework Manager package created
from the PowerCube into the Average Monthly Revenue dimension of the Store Cost cube.
Steps
1. From the Content Administration page on the Configuration tab in IBM Cognos Administration,
click Planning and then click Macros.
2. Click Run with options for the Import Average Monthly Revenue macro, and select to run
now.
Tip: You can view the progress of the macro in the Monitoring Console on the Macros tab.
Need more help?
● "Run a Macro from IBM Cognos Connection" (p. 225)
Create and Publish a Framework Manager Package
To use the go_new_stores_contributor application as the basis for reporting, you must create a
Framework Manager package. After the package is created and published, it can be used to trigger
events and create reports.
Steps
1. Publish the go_new_stores_contributor application using Table-only Layout publish.
Include all cubes and e.List Items in the publish and configure a Publish Datastore. Name the
datastore, go_new_stores_table, and add it to the job server cluster.
Tip: Clear Prefix column names with data type on the Options tab.
You can view the progress of the publish in the Monitoring Console on the Job Server Clusters
tab.
Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
2. Run the Generate Framework Manager Model admin extension. Name the package
new_stores_FM_model and store the Framework Manager Model in \samples\
Planning\Contributor\en\Data\Data_go_new_stores_contributor.
Administration Guide 317

Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
318 Contributor
Select all cubes and the data source query subjects Unformatted lists and Complete hierarchy
lists for the model.
3. In Framework Manager, open the model created by the Framework Manager extension.
4. Create a filter on Measure Dimension Promotions Plan to exclude the ALL RETAILERS D-List
item.
Tip: Double-click on the Measure Dimension Promotions Plan in the Business View and click
the Filters tab. Use Retailer Type and the not like operators.
5. Rename Complete Dimension 2eList to REGIONS from within Promotions Plan/Complete Star
Schema for Promotions Plan.
Tip: Planning levels are numbered in Framework Manager. To make them easier to use in
Report Studio, rename the levels to reflect the content.

Create a Report
Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
6. Select the new_stores_FM_model package and publish the package to make it available in IBM
Cognos Connection.
Need more help?
● "Create a Table-only Publish Layout" (p. 277)
● "The Generate Framework Manager Model Admin Extension" (p. 306)
● See the IBM Cognos 8 Framework Manager User Guide
You are now able to create a report on Planning data to compare the cost of promotions against
the planned promotion value. This report will use a crosstab report to compare information that
uses one or more criteria and a chart to reveal trends and relationships.
Your final report for budget version 1 will look like this.
Administration Guide 319

Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
320 Contributor
Steps to Create the Crosstab
1. In Report Studio, create a new blank report that uses the sample package named
new_stores_FM_model.
2. Create a table (2 columns by 4 rows) to be used as the template for the report.
Tip: Use the tool box to drag a table into the report area.
3. Using a text item, create headings for Budget Version 1 (Central Europe) and Budget Version
2 (Central Europe).
Tip: Drag a text item to the first and the third rows of the first column.
4. Drag a crosstab to the cell in the second row of the first column.
5. Add Central Europe from the following hierarchy - Business View/Promotions Plan/Complete
Start Schema for Promotions Plan\REGIONS\Complete hierarchy 2 eList\Members\Complete
hierarchy 2eList(All)\All Subsidiaries\All Europe.
Tip: Use the Source tab in the Insertable Objects pane.

Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
6. From within Promotions Plan, add the following data items to the rows:
● From Measure Dimension Promotion Plan select Franchise/Corporate
● From Measure Dimension Promotion Plan select Month of Promotion
● From Complete Star Schema for Promotions Plan, select Members 1 through 10 from the
Complete Dimension 3 ID numbers
● From Measure Dimension Promotion Plan select Retailer Type
Note: Make sure you choose the Retailer Type that you changed in your model. Drag
Retailer Type to each member 1 - 10.
7. In the Query Explorer, drag the Budge version 1 dimension from Complete Dimension 5 Versions
in to the Slicer.
Administration Guide 321

Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
322 Contributor
8. From within Promotions Plan, add the following Measure Dimension Promotions Plan data
items to the columns:
● Promotion Costs
● Planned Promotion Value
Note: To hide the ID numbers, edit the ID text to override the default text.
9. In the Query Explorer, add Average Monthly Revenue to Data Items from New Store Plan and
use the Budget version 1 dimension in the Slicer.
10. Copy and paste the crosstab into the cell in the fourth row of the first column.
Tip: Select the crosstab in the properties pane to create the copy.
11. Create a second query, a copy of Query1, and apply it to the second crosstab. Change the Slicer
so that Query 2 applies to Budget version 2.

Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
12. Run the report to view the crosstabs.
Your crosstabs for budget version 1 and budget version 2 will look like this.
Administration Guide 323

Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
324 Contributor
Steps to Create a Combination Chart
1. From the tool box, drag chart to the table cell to the right of the crosstab in the second row.
Select the default combination chart. In the properties pane for the combination chart, change
Query to Query1 to use the Budget Version 1 data.
2. From the data items Insertable Objects tab for Query 1, drag the following data items into
the Category (x-axis):
● Central Europe
● Franchise/Corporate
● Month of Promotion
3. Drag the following data items from Query 1 into the Series:
● Promotion Costs
Below Promotion Costs, add the ID series one through ten (1-10)
Hint: Drag each number and drop within each previous number.
● Planned Promotion Value
For Planned Promotion Value, change the chart type to line.
● Average Monthly Revenue
4. Create a Statistical Maximum Baseline in Properties, Chart Annotations, Baselines. Click OK.

5. Set Planned Promotion Value in the baseline properties.
6. Change the Combination Chart Axis property of the Y2 Axis to Show.
7. Reset the Y1 Axis maximum value to 400,000.
Hint: Click the vertical scale on the left side of the chart, and then in the Properties - Y1 Axis
box, set the Maximum Value.
8. Change the Line Styles to dotted red line and rename Statistical Maximum to Planned Promotion
Value.
Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
Administration Guide 325

Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
326 Contributor
9. Copy and paste the combination chart into the cell in the fourth row of the second column and
apply Query 2 to the second crosstab.
10. Run the report to view what it will look like.
11. Save the report as Central Europe Promotions Report.
Your charts for budget version 1 and budget version 2 will look like this.

Need more help?
● See the IBM Cognos 8 Report Studio User Guide
Create an Event Studio Agent
Create and schedule an Event Studio Agent to deliver the report as a news item on the first day of
every month if the value of the planned promotions is greater than $20,000.
Tip: Create a signon to the data source connection so that users don’t have to enter database cre-
dentials when they run reports or reports are run by an event. For more information, see the section
Create or Modify a Data Source Signon in the IBM Cognos 8 Administration and Security Guide.
Steps
Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
1. Open Event Studio using the package named new_stores_FM_model.
2. Create an agent with an event condition expression for Planned Promotion Value greater than
20,000. This event will be scheduled to run once a month, the event condition expression will
return a result so the event is triggered.
Tip: The Expression should look like the following:
[Promotions Plan Value]>20000.
Validate the expression , then preview the results to check that the expression returns
a result.
3. Include the Run a report task and select the Central Europe Promotions Report.
Administration Guide 327

Chapter 19: Example of Using IBM Cognos 8 Planning with Other IBM Cognos Products
328 Contributor
4. Include a Publish a news item task.
In the Headline box, type Central Europe New Store Promotions Available.
Under Link to, click Select an entry and select the Central Europe Promotions Report.
5. Select My Folders as the News list locations. The news item will be published to this location.
6. Click Schedule the agent … and select the By Month tab. Schedule the agent for the first day
of every month.
7. Save the event as New Stores Event. In IBM Cognos Connection, click Run with options ,
for the New Stores Event to run the event now.
View the news item, containing Central Europe Promotions Report, in IBM Cognos Connection
on the My Folders tab. This news item will be created the first day of every month.
Need more help?
● See the IBM Cognos 8 Event Studio User Guide

Chapter 20: Upgrading IBM Cognos 8 Planning -
Contributor
You can upgrade users, user classes, groups, libraries, and Contributor applications from previous
IBM Cognos Planning versions. Depending on your version, you can upgrade the entire Planning
Application Database or you can upgrade individual applications.
Use the following table to determine which upgrade tool you need according to the version of
Planning you currently have installed.
Upgrade Tool
Planning Administration
Domain Wizard
Upgrade Application Wiz-
ard
Deployment Wizard
Current Planning
Version
7.3
8.1
7.2
7.3
8.1
8.2 or higher
Description
Upgrades applications, administration links,
and macros from the source Planning
Administration Domain.
The security and access rights for the Planning
Administration Domain objects are remapped
in the new environment.
Upgrades individual or multiple applications
at once.
The security of each application is updated
in the new environment, but the access rights
are not updated.
Enables you to export and import complete
models, macros, administration links, or
Analyst libraries.
You can export individual or multiple Plan-
ning Administration Domain objects.
For detailed information about the upgrade process for Planning, see the IBM Cognos 8 Planning
Installation and Configuration Guide.
Upgrade the Planning Administration Domain
Administrators use the Planning Administration Domain Wizard from the Contributor Administra-
tion Console to upgrade Planning Administration Domains. Each Planning Administration Domain
must be upgraded separately.
Administration Guide 329

Chapter 20: Upgrading IBM Cognos 8 Planning - Contributor
330 Contributor
When you upgrade from IBM Cognos 8 Planning version 7.3, we recommend that you upgrade the
Planning Administration Domain into the current Planning store.
When you upgrade from IBM Cognos 8 Planning version 8.2, you upgrade the Planning Adminis-
tration Domain and the associated applications at the same time.
Before you upgrade the Planning Administration Domain, you must configure at least one datastore
(p. 48), job server cluster (p. 56), and job server (p. 56).
Steps
1. In the Contributor Administration Console, click Tools, Upgrade Planning Administration
Domain.
2. Click Next.
3. Configure the datastore server connection for the datastore server that contains the Planning
Administration Domain.
4. Select the Datastore provider.
The options are SQL Server, Oracle or DB2.
5. Do one of the following:
● For SQL Server, enter the Datastore server name, or click the browse button to list the
available servers
● For Oracle, enter the service name.
● For DB2, enter the database name.
6. Enter the information as described in the table below:
Setting
Trusted Connection
Use this account
Password
Preview Connection
Description
Click to use Windows authentication as the method for
logging on the datastore. You do not have to specify a sep-
arate logon id or password. This method is common for
SQL Server datastores and less common, but possible, for
Oracle.
Enter the datastore account that this application will use to
connect. This box is not enabled if you use a trusted connec-
tion.
Type the password for the account. This box is not enabled
if you use a trusted connection.
Provides a summary of the datastore server connection
details.

Setting
Test Connection
Description
Mandatory. Click to check the validity of the connection
to the datastore server.
7. If you want to configure advanced settings, click Advanced.
Typically these settings should be left as the default. They may not be supported by all datastore
configurations.
Enter the following information.
Setting
Provider Driver
Connection Prefix
Connection Suffix
Description
Select the appropriate driver for your datastore.
Specify to customize the connection strings for the needs of
the datastore.
Specify to customize the connection strings for the needs of
the datastore.
8. Select the Planning Administration Domain that you want to upgrade, test the connection, and
click Next.
9. Click the namespace to secure the objects against and click Next.
10. If you want to upgrade existing Planning Administration Domain objects, select the Replace
objects if they exist in the current Planning Store check box.
If you do not select this option and the objects exist, they are not upgraded.
11. Click Next.
12. In the Map Planning Administration Domain Objects page, in the Target column, click the
options that you want.
You must map the job servers and job clusters that are configured in the source Planning
Administration Domain to the upgraded job server and job server clusters so that macros are
upgraded correctly.
13. If you want to choose defaults that apply to all applications, click Map All Applications and
complete the fields.
14. Click Finish.
A log located in the %Temp%epUpgrade directory notifies you of any warnings that occur while
upgrading the Planning Administration Domain.
Chapter 20: Upgrading IBM Cognos 8 Planning - Contributor
Administration Guide 331

Chapter 20: Upgrading IBM Cognos 8 Planning - Contributor
Upgrade Contributor Applications
332 Contributor
You can upgrade an individual application or multiple applications at once.
Tip: Upgrade applications separately if the end of the plan year for each application is different
and you do not want to upgrade an application mid-year.
Before you use the Upgrade Application Wizard, do the following:
❑ Upgrade your directory server.
❑ Upgrade other IBM Cognos products.
❑ Stop scheduled scripts from running, if appropriate.
❑ Ensure that all jobs are complete.
The Upgrade Application Wizard does not upgrade the following:
● data in the source application
● Admin extensions
IBM Cognos Planning 7.2 Admin extensions are removed because substantial changes were
made to the extensions for the current version.
● audit information
History table data and Job metadata is not upgraded. When the Go to Production process is
run, cut-down model information is automatically generated after upgrading.
● Contributor for Excel
This is a separate Web client installation. To upgrade, the previous version must be uninstalled
and the new version installed.
● scripts
In Contributor 7.2, you automate Contributor functionality using scripts. This functionality
was replaced by macros. You cannot migrate your 7.2 scripts to macros. For more information,
see "Automating Tasks Using Macros" (p. 193).
● published data
Publish datastores are not upgraded. Prior publish datastores can be retained and are compatible
with 8.3. However, if you need to recreate your publish datastore as part of your 8.3 deployment,
it is recommended that you rebuild it as UTF-16 to better conform to global business standards
and to ensure easier compatibility with future IBM Cognos releases.
You cannot publish to the Contributor application container. You must publish to a separate
container. We recommend that you compare the results of publishing from earlier versions of
Contributor with publishing in the current version to ensure that the publishing is performing
as required. Any publish scripts must be re-created using the new macro functionality.
● Analyst>Contributor links
When you upgrade applications that contain Analyst>Contributor links, you must open the
link in Analyst and reselect the source and target of the link. For more information, see "Update

a Link from a Computer That Cannot Access the Original Datastore" (p. 351), and the Analyst
User Guide.
Analyst and Contributor macros that use Analyst>Contributor links will fail if you do not
update the source and target of the link.
To upgrade an application, you must have the Planning Rights Administration capability. By default,
this capability is granted to the Planning Rights Administrators role.
Before upgrading an earlier Contributor version to the current version, we recommend that you
install on a separate server and then upgrade each application.
We recommend that you back up the data stores that you intend to upgrade.
For more information, see "Security" (p. 29) and the IBM Cognos 8 Administration and Security
Guide.
Steps
1. Under Datastores, click the required datastore, right-click Applications, and click Upgrade
Application.
2. Click Add.
3. Select the Datastore provider.
The options are SQL Server, Oracle or DB2.
4. Do one of the following:
● For SQL Server, enter the Datastore server name, or click the browse button to list the
available servers
● For Oracle, enter the service name.
● For DB2, enter the database name.
5. Enter the information as described in the table below:
Setting
Trusted Connection
Use this account
Password
Chapter 20: Upgrading IBM Cognos 8 Planning - Contributor
Description
Click to use Windows authentication as the method for
logging on the datastore. You do not have to specify a sep-
arate logon id or password. This method is common for
SQL Server datastores and less common, but possible, for
Oracle.
Enter the datastore account that this application will use to
connect. This box is not enabled if you use a trusted connec-
tion.
Type the password for the account. This box is not enabled
if you use a trusted connection.
Administration Guide 333

Chapter 20: Upgrading IBM Cognos 8 Planning - Contributor
334 Contributor
Setting
Preview Connection
Test Connection
Description
Provides a summary of the datastore server connection
details.
Mandatory. Click to check the validity of the connection
to the datastore server.
6. If you want to configure advanced settings, click Advanced.
Typically these settings should be left as the default. They may not be supported by all datastore
configurations.
Enter the following information.
Setting
Provider Driver
Connection Prefix
Connection Suffix
Description
Select the appropriate driver for your datastore.
Specify to customize the connection strings for the needs of
the datastore.
Specify to customize the connection strings for the needs of
the datastore.
7. Select the application that you want to upgrade, test the connection, and click Next.
8. Choose whether to create the datastore now and continue upgrading the application (Create
and populate datastore now) or to exit the wizard and create and populate the datastore using
scripts Generate datastore scripts and data files. Then, in either case, click Next.
9. If you chose to use a script, give the script to your DBA to have the datastore created.
You can later link to the new datastore using the Contributor Administration Console which
will resume the upgrade wizard.
10. If you chose to create the datastore now, do the following:
● Click the namespace which will secure the upgraded application and click Next.
● Click Finish.
The Upgrade Application(s) page appears with the application that you specified added to
the list of applications that can be upgraded.
● Repeat steps 1 to 10 for each application that you want to upgrade.
● Click Upgrade.
The results of the upgrade show in the Upgrade log for application(s) page.

The wizard:
● creates a new application datastore, or enables you to create a script that can be run by a
database administrator
● shows you if there are users who are working off-line because off-line data cannot be upgraded
due to a new caching file that is used in the current version of Contributor
● automatically updates Contributor translation information in the datastore, requiring no manual
configuration
● upgrades access tables and saved selections requiring no further configuration
● retains all configuration options, except those stated
● saves an import/upgrade log named application_dataStore_ImportLog.txt to your
%temp%/epUpgrade directory
● upgrades the following client extensions for the Classic Contributor Web Client: Excel Export
(Export for Excel), Client Loader (Get Data), Excel Print (Print to Excel)
● applies default access rights
For more information, see "Configuring Access to the Contributor Administration Con-
sole" (p. 38).
You must add the application to a job server or job server cluster (p. 52), run Go to Production
(p. 243), and set up the Contributor Web site to enable users to access Contributor applications
(p. 78).
Upgrade Security
If your version 7.2 Planning application was secured using Contributor native security, you can
upgrade directly to a IBM Cognos 8 namespace.
If your Planning application or Planning Administration Domain was secured by a Series 7 namespace
that was administered by Access Manager, you can upgrade your security to an IBM Cognos 8
namespace using the Contributor Administration Console deployment wizard.
To upgrade your security, you must configure IBM Cognos 8 Planning to use both the Series 7
namespace that was originally used as well as the namespace to which you are upgrading.
You can use the Deployment Wizard to export the Planning application or the Planning Adminis-
tration Domain, and then import the application or domain again. During the import, you can map
the security to your new namespace.
Chapter 20: Upgrading IBM Cognos 8 Planning - Contributor
After you have upgraded the security for all of your applications or your Planning Administration
Domain, you can remove the Series 7 namespace from your configuration.
For more information, see "Deploying the Planning Environment and Viewing the Status of
Deployments" (p. 170) and the Installation and Configuration Guide.
Administration Guide 335

Chapter 20: Upgrading IBM Cognos 8 Planning - Contributor
Accessing Contributor Applications
336 Contributor
Contributor applications are accessed from the IBM Cognos Connection portal, typically http://
servername/cognos8.
For users with bookmarks to the Contributor client, either inform users of the application URL,
or use URL redirection to the new URL.
We recommend that you use the full client installation to deploy the Web application to the Web
client computer rather than the CAB download option if you have limited WAN bandwidth or your
users do not have sufficient rights to their local machine to install the CAB files.
For more information, see the IBM Cognos 8 Planning Installation and Configuration Guide.

Chapter 21: Analyst Model Design Considerations
You can design an Analyst model to be used for a Contributor application and create links between
Analyst and Contributor (p. 347).
Designing an Analyst Model for Contributor
When designing an Analyst model that is used to create a Contributor application, the following
things must be considered:
● "Analyst Library Guidelines" (p. 337)
● "D-Cube Restrictions" (p. 338)
● "D-Links" (p. 339)
● "Dimensions" (p. 341)
● "Creating Applications with Very Large Cell Counts" (p. 345)
Analyst Library Guidelines
When you design an Analyst model to be used for a Contributor application, consider whether it
has D-Lists, formats, and A-Tables that can be shared with other Contributor applications. If so,
you can create a common library to contain any D-Lists to be shared between Analyst models. You
then create the main Analyst library, which must contain all D-Cubes, the e.List, and all update
links.
The following restrictions apply:
● A maximum of two libraries can be used per Analyst model.
All objects on which the model depends must be contained in the main library and the common
library.
● Update links must target the specific cubes in the main library.
● The Contributor administrator must have write access to all objects used in the Analyst model.
● D-List names used by the Analyst model must be unique.
This includes D-List used as format lists.
● D-Cube names must be unique.
● If a cube consists of D-Lists that are all from the common library, it is an assumption cube.
Because of this, such assumption cubes do not appear when selecting the e.List in the Adminis-
tration Console during application creation.
● D-Cubes used as allocation tables must be contained in the main library.
Administration Guide 337

Chapter 21: Analyst Model Design Considerations
D-Cube Restrictions
You do not explicitly select the other library. This is the first library other than the template library
that is referenced when looking for dependencies on other objects. If there are references to more
than one other library, errors are reported. It may be necessary to trace dependencies in Analyst to
establish where the reference occurred.
D-Cube options can cause problems in Contributor applications.
The following options are not supported in Contributor but do not stop a Contributor application
from working:
● All settings in the D-Cube, Options menu: Widths, Lines, Zeros, Break-back, and Stored Copy
● Integer break-back
This is ignored, producing different results in Contributor if break-back is switched on in
Contributor
● D-Cube Sort
The following D-Cube cell options are ignored: holds, locks, protects, and annotations.
Forward-referenced Weighted Averages
338 Contributor
Forward-referenced weighted averages prevent a Contributor application from being created and
synchronized.
If you weight an item by a calculated item, the priority of that calculated item must be lower than
the priorities of subtotals in other dimensions. Or, if all the priorities are equal, the dimension
containing the weighted average must be first in the D-Cube dimension order.
Forward weighted averages are present if an item is weighted by a high priority calculation, and
subtotals in other dimensions are medium or low priority. e.List review items are medium priority
subtotals in a Contributor application, regardless of any priority settings in the Analyst placeholder
e.List. Forward weighted averages are also present if an item is weighted by a medium priority
calculation, and other dimensions containing medium or low priority subtotals appear in the D-
Cube dimension order.
This restriction applies both to assumption and contribution cubes.
Example
In the following example, Sales is calculated as Total Units * Price and Price is weighted by Total
Units.
The weighted average in Price, Q1 is calculated correctly by Contributor if the weightings in cells
Total Units, Jan to Total Units, Mar are already calculated. In other words Q1 must be a higher

D-Links
priority calculation than Total Units. Or, if equal priority, the time dimension should be later in
the cube than the Sales calculation dimension.
If Total Units is higher priority than Q1, the cell Price, Q1 are calculated before the weightings in
cells Total Units, Jan to Total Units, Mar are calculated. As a result, the weighted average could
not be calculated correctly.
There is a lot to consider relating to D-Links when designing a Contributor model in Analyst.
Target areas of D-Links are automatically protected in Contributor to prevent a D-Link from
overwriting data provided by a planner. You do not have to protect D-Link target areas using access
tables.
D-Links Run Automatically in Contributor
Special D-Links
All model update D-Links must be included in D-Cube update lists, but there is no need for update
macros. This is because when a planner clicks on a tab in the Web front end, Contributor checks
whether any D-Links into the cube must be run. They do not need to be run if the source data for
the D-Links is unchanged. If D-Links must be run, Contributor runs all the update D-Links for the
cube in the order they appear in the D-Cube update list before the selected tab appears.
When a planner saves or submits, Contributor checks again to see whether D-Links must be run.
These links are run before data is sent back to the server.
Data in a model can be changed using the Contributor Administration Console through assumption
cubes (after application creation or synchronize), or by importing data. Planners see a changed
application after all changed data blocks are updated through the reconciliation process.
D-Links not included in D-Cube update lists are ignored, as well as import D-Links, which are D-
Links from external sources.
In Contributor, update links are used in the Contributor model only if the Execute check box for
the D-Link is selected.
Lookup D-Links, internal D-Links, and some break-back D-Links run automatically as relevant
data is changed on a particular tab.
For example, with lookup D-Links, if a planner changes a D-List formatted value in the lookup
target cube and presses Enter, lookup D-Links are run into the cube.
Automatically executing internal D-Links can be useful for solving problems, such as to express
values as a percent of a total. A lookup link can change its own source data so that the same D-
Link needs to be run again. In Contributor, such internal D-Links run until the source data stops
changing or up to a maximum of 100 times.
A D-Link that targets a subtotal to perform a break-back allocation to detail items is named a
break-back D-Link. The detail items can be writable by a planner, although normally another D-
Link supplies the weightings for these detail items. The planner can change values in these detail
items if they are not supplied by another D-Link. The break-back D-Link runs automatically when
they press Enter.
Chapter 21: Analyst Model Design Considerations
Administration Guide 339

Chapter 21: Analyst Model Design Considerations
D-Links and Data Types
Invalid D-Links
340 Contributor
The Contributor D-Link engine has a formal treatment of data types that Analyst does not have.
Contributor recognizes four data types: number, date, text, and D-List formatted.
Some operations on these data types are not supported in Contributor. For example, the Contributor
link engine does not:
● transfer D-List formatted values into numeric formatted cells
● add numbers to D-List formatted items
● multiply dates
● subtract text from numbers
● add, multiply, or subtract text values or D-List formatted items
All operations on mixed data types are considered invalid by the Contributor link engine with one
exception. You can add numbers to or subtract numbers from dates.
The results obtained in Contributor when performing invalid data type operations depend on the
D-Link mode. Fill puts zeros into the relevant target cells, whereas Substitute leaves the relevant
target cells alone. Add and Subtract effectively behave like Substitute, adding or subtracting zero.
In Analyst, all operations on data types are permitted. The Analyst D-Link engine simply operates
on the underlying values.
Invalid D-Links prevent Contributor applications from being created, and also prevent synchroniz-
ation.
D-Links that use the e.List in any way other than the following are invalid:
● Link between an assumption cube, which does not have an e.List, and the target, a cube with
an e.List, where nothing is selected and it is unmatched.
● Where the e.List is present in both the source and the target, and the matching is done using
match descriptions with the default options: Case Sensitive On, Match Calculated Target Items
Off.
The following are invalid D-Links:
● A D-Link from a cube with the e.List that targets an assumption cube.
● D-Cube allocation tables that are not assumption cubes, which means they contain the e.List.
● Allocation tables that contain deleted dimension items but which have not had these items
removed or edited in Analyst.
● A D-Link that needs editing.
Analyst issues a warning such as:
A dimension has been removed from the target
cube since
the link was last saved. Please edit and resave the link.

● A D-Link that targets the wrong cube.
For example, you include a D-Link in an update list for a particular cube. Then, by editing the
D-Link, you change the target cube of the link, leaving the D-Link in the update list for the
original cube.
D-Links Between Assumption Cubes and Contribution Cubes
Dimensions
Dimension Order
D-Links between contribution cubes and from an assumption cube to a contribution cube are
allowed.
D-Links between assumption cubes have no effect in a Contributor application, but do not cause
an error or warning. You should run the D-Link in Analyst before building the model.
D-Links from a contribution cube to an assumption cube are not allowed.
A dimension is also referred to as a D-List in Analyst. Consider the following when designing
dimensions:
● "Dimension Order" (p. 341)
● "Supported BiFs" (p. 343)
● "Format Priorities in Analyst and Contributor" (p. 345)
● "Scaling Differences Between Analyst and Contributor" (p. 345)
As a general rule, in an Analyst model, choose dimensions in the following order:
1. Calculation D-Lists such as P&L, and Balance sheet D-Lists.
2. The e.List.
3. Other aggregation D-Lists, such as products, customers, divisions, cost-centers, regions, or
subsidiaries.
4. Time D-Lists, such as months, quarters, or years.
5. Only one timescale D-List can be chosen in each D-Cube.
6. Control D-Lists, such as Actual/Budget/Variance.
We recommend that the e.List is second in the dimension order, because this affects the size of the
data blocks. The data blocks store all detail cells for each cube, together with any calculated cells
for which the calculation comes earlier in the calculation sequence than the aggregations up the
e.List. These calculations are referred to as pre-aggregation calculations. The dimension order is
the primary method for controlling the calculation sequence. As a result, the position of the e.List
in the dimension order affects the number of cells stored in the blocks, and therefore the block size.
In many cases you can choose a different dimension order without affecting the calculations, and
this can be used to minimize the block size.
Chapter 21: Analyst Model Design Considerations
Administration Guide 341

Chapter 21: Analyst Model Design Considerations
Example
For example, in the cube Revenue Plan, the dimensions are
● Product Gross Margin
● Indoor and Outdoor Products
● Channels
● e.List
● Months
● Versions
With this order, the calculated items on the dimensions Indoor and Outdoor Products and Channels
are stored on the data blocks.
The dimensions can be reordered as follows without changing the calculation results
● Product Gross Margin
● e.List
● Indoor and Outdoor Products
● Channels
● Months
● Versions
The calculated totals on the products and channels dimensions are no longer stored on the data
blocks. They are recalculated when the data is loaded on the client or during publish. In general,
the e.List is not the first dimension because there is typically one dimension of the cube for which
the calculations must be pre-aggregation. However, in many cubes there are other hierarchical
dimensions in addition to the e.List (products and channels in the example), and the order of these
can be switched without affecting the calculations.
Low priority calculations are pre-aggregation and are always stored on the data blocks regardless
of dimension order. High priority calculations are post-aggregation and are never stored on the
data blocks.
Hierarchial Dimensions in Analyst
342 Contributor
For a dimension to be shown as a hierarchy in Analyst, the following requirements need to be met:
● The dimension must not be a time dimension.
● The dimension’s items must all be detail or simple sums.
● Do not use weighted or time averages.
● Do not use the Force to Zero calculation option.
● Priorities can only be 0 or 10.
● Do not use any formatting.

Supported BiFs
When creating dimensions that are used in cubes in the Contributor application, the following BiFs
(built in functions) are available. For information about each BiF, see the Analyst User Guide.
@Cumul
@Days
@DaysOutstanding
@DCF
@Decum
@Delay
@DelayDebt
@Delay Stock
@DepnAnnual
@Deytd
@Differ
@Drive
@ErlangDelayAgents
@ErlangDelayFull
@ErlangDelayLite
@ErlangLossLite
@Feed
Switch-over Dates and Generic Time Scales
@Forecast
@Funds
@FV
@Grow
@ICF
@IRR
@Lag
@Last
@Lease
@Lease Variable
@Linavg
@Mix
@MovAvg
@MovMed
@MovSum
@NPer
@NPV
@Proportion
@PV
@Rate
@Repeat
@SeasonLite
@StockflowAF
@Tier
@Time
@Time (Methods
2,3,4,5,6,7,8,9,10,12,15,16)
@Timesum
@TMin
@TMax
@TRound
@Ytd
A switchover date is used by certain BiFs to define the dividing point between past and future.
Generic time scales have no date associated with each period and all the periods are the same length.
For all BiFs, switch-over dates cannot be used in conjunction with generic time scales.
For @NPV and @IRR, use of generic time scales is not supported.
Chapter 21: Analyst Model Design Considerations
Administration Guide 343

Chapter 21: Analyst Model Design Considerations
@Last Differences
@Last looks back along the series of data in the input row and returns the most recent non-zero
value.
@Time Restrictions
Date Formats
344 Contributor
In Analyst, any positive number greater than 1E-13 is non-zero. Negative numbers must be greater
than -1E-12.
In Contributor, any positive number greater than 1E-15 is non-zero. Negative numbers must be
greater than -1E-14.
The implementation of @Time in Contributor is identical to the implementation in Analyst except
for the following restrictions:
When using Method 1, the calculation will give different results depending whether the dimension
on which the calculation is defined comes before or after the e.List in the D-Cube's dimension
sequence. In other words, its results depend on the time at which it is executed.
@Time is not supported in Contributor in the circumstances listed below. In all these cases the
function returns zero.
● Method 2 (date last saved) is not supported. If you use @Time(2) in a D-List, a warning appears
while you create or synchronize the application, and the result is always 0.
● Methods 3, 4, 5, 8,10, 12, and 16 return a result of 0 with generic timescales.
● Methods 9 and 15 return a result of 0 with a generic timescale, or if the switchover date is not
set.
For information about using these built in functions, see the IBM Cognos 8 Planning - Analyst User
Guide.
The following date formats are supported. Using any others prevents a Contributor application
from being created and prevents synchronization.
DD/MM/YY
DD.MM.YY
MM/DD/YY
MM.DD.YY
DD-Mon-YY
DD Mon YY
Day DD-Mon-YY
YYYYMMDD
DD-MM-YYYY
MM-DD-YYYY
DDMMYYYY
MMDDYYYY
DD/MM/YYYY
MM/DD/YYYY

YY-MM-DD
YYYY-MM-DD
YYMMDD
Format Priorities in Analyst and Contributor
DD.MM.YYYY
MM.DD.YYYY
In Analyst, there is a rule of precedence between the various formats, based on a priority among
the data types as follows:
● dimension (first)
● text/date/time/number (equal second)
A dimension format applied on any dimension overrides a text/date/time/number format on any
other dimension. If different formats with the same priority are applied on different dimensions,
the first of these formats is used, taken in dimension order. Analyst treats formats applied to the
D-Cube consistently with those applied to dimensions: a format applied to the cube is included in
sequence after all the other dimensions. Thus, a dimension format applied to the cube overrides
text/date/time/number formats on the dimensions, but is overridden by another dimension format
on a dimension.
In Contributor, the format is tied to the calculation priority and dimension order. This means that
a format on a calculated item applies to all cells to which that calculation applies. However, this
means that there are cases where Contributor and Analyst resolve the formats differently when
formats are applied to detail items on two dimensions.
Lower ordered dimensions take priority in Contributor, which means that the second dimension
has formatting priority over the first, and the third has priority over the second. High priority cal-
culations have priority over any format on a detail item. A high priority calculation format on the
third dimension overrides a high priority calculation format on the second dimension, and so on.
Scaling Differences Between Analyst and Contributor
Where an item in a D-List has a scaling format applied, the behavior is different in Analyst and
Contributor.
● In Analyst the numbers are entered, ignoring any scaling applied in the formatting. For example,
an item is scaled to 1000s. If you type in 22k, it shows as 22, because the underlying value is
22000. If you type in 22, it shows as 0, because the value is 0.022k, assuming that less than
two decimal places are showing.
● In Contributor, the numbers are entered as shown. If the cell shows 1000 for an underlying
value of 10, and you type in 1200, the new value shows as 1200 with the underlying value now
being 12.
Creating Applications with Very Large Cell Counts
Chapter 21: Analyst Model Design Considerations
When creating or synchronizing an application, the system must check for forward-referenced
weighted averages. It opens as many items from each cube as necessary to see whether forward-
Administration Guide 345

Chapter 21: Analyst Model Design Considerations
Example
referenced weighted averages exist. In some cases, this can cause the system to run out of memory,
such as when very large cubes are used in the Analyst model. Access tables are applied to cubes to
reduce their size when used in Contributor.
Rules exist to determine which items are opened. All items are selected from any dimension that
has any calculations other than simple sums, has weighted averages or other calculation options,
or has formats or time scales. If the dimension is all-detail, only the first item is selected. If the
dimension has some calculated items, the first level subtotal with the fewest children is selected,
with its children.
For most large cubes, the entire cube is not opened. Problems can occur when every dimension that
is not a simple hierarchy consists of a number of detail items, and a single total. In such a case, the
entire cube would be opened.
You can make small changes to such cubes so that the application can be created. For example,
this dimension would be opened in full:
A
B
C
:
:
Z
Total (A to Z) = A+B+C+...+Z
You can include additional calculated items to the hierarchy so that these items are opened instead
of the total of all detail items.
For example, you can add this extra dummy total.
Total A = +A
Then, when the check for forward-referenced weighted averages is performed, only items A and
Total A are used, reducing the memory requirements by a factor more than 10. Such a dummy total
can be excluded from the Contributor application by setting it to no-data in an access table.
It is also good practice in such cases to keep the Analyst cube as small as possible by including only
a single-item e.List.
Break-Back Differences Between Analyst and Contributor
346 Contributor
Break-back in Contributor is slower than in Analyst. However, forward calculations in Contributor
are the same, or slightly faster.

AnalystContributor Links
You can transfer data between Analyst and Contributor using the Analyst D-Link function. All the
standard features of a D-Link are available, such as the use of A-tables, D-Cube allocations, local
allocation tables, match descriptions, and matching on codes.
These types of links are available:
● Analyst to Contributor
● Contributor to Analyst
● Contributor to Contributor
For small amounts of data, an AnalystContributor link can be a quick and effective method of
transferring data. However, for large amounts of data, it is more effective to use "Administration
Links" (p. 147).
AnalystContributor links work in the same way as a standard Analyst D-Link. They treat Con-
tributor as a single large cube, which means that with large models, you can quickly run into memory
problems. We recommend that AnalystContributor links be used only for ad-hoc transfers of
small amounts of data of no more than 5 to 10 e.List items.
You can avoid memory problems for links that target an entire e.List in Contributor by using the
@SliceUpdate macro. This macro processes the link in slices of the e.List, making it a much more
scalable solution.
Most D-Links that have Contributor as a source or target behave the same as standard Analyst D-
Links. The few exceptions are as follows:
● Only cubes that contain the e.List are available as a source or target for AnalystContributor
links.
● Lookup D-Links are not allowed when Contributor is the target.
This is because Lookup D-Links depend on the data in the target cube. In a Web environment,
this data can be changing all the time.
● You cannot target calculated items in Contributor.
This includes totals on the e.List dimension as well as any total in other D-Lists.
● Match descriptions in Analyst D-Links to or from Contributor treat the pipe symbol as a blank.
The pipe symbol is used in Analyst as a line-feed for column headers. It is stripped out when
you create a Contributor application from an Analyst model.
● You cannot target an assumption cube in Contributor, or use it as a source.
● You cannot target No Data cells as defined by Access tables in Contributor.
However, as the Administrator, you are not subject to the restrictions imposed on Contributor
users entering data using the Web client. Hidden and read-only cells are not applicable. You
can write to these cells just as you can using normal import routines.
● AnalystContributor links cannot be run inversely.
Chapter 21: Analyst Model Design Considerations
Administration Guide 347

Chapter 21: Analyst Model Design Considerations
Otherwise, most D-Link types are permitted. You can use Match Descriptions, local allocation
tables, A-tables, and D-Cube allocations. You can cut subcolumns, so that you can match on codes.
You can run accumulation links both ways, but lookup links run from Contributor to Analyst only.
If you use a saved allocation table and rename D-List items in the Contributor application when
using Contributor as a source or target in a D-Link, the allocation table must be manually updated
for the link to work.
Analyst users who do not have the Contributor Administration Console installed are not able to
run AnalystContributor D-Links.
When you install Client tools onto a workstation, it is installed only for the user doing the installa-
tion.
To run a ContributorAnalyst link, users must have Analyst and the Contributor Administration
Console installed. They must also have rights to Analyst and the appropriate Contributor applica-
tions.
In addition, organizations may prevent access to the database or the Web server using the IP address,
limiting who can run these D-Links.
D-Links from ASCII and ODBC directly into Contributor are not allowed. You must use Contributor
Import to do this.
Set Up a Link Between Analyst and Contributor and Between Contributor
Applications
You set up a link between Analyst and Contributor or between Contributor applications in the
same way as you would a standard D-Link, choosing Contributor as the source or target of a D-
Link. Only cubes that contain the e.List item are available as a source or target for these links. All
the data is prepared in Analyst.
Steps
1. In the Analyst D-Link editor, choose Contributor Data as the source or target.
2. If more than one datastore server is available, choose one.
3. Click a Contributor application.
Tip: You may need to click the Refresh button to the right of the Name list to view the list of
available Contributor applications.
4. Click Test Connection, and click OK.
5. Click a Contributor cube.
6. Pair dimensions against the target (or source) cube as you would for a standard D-Link.
Analyst>Contributor D-Links
348 Contributor
These links can target either the production or development version of Contributor. If targeting the
development version, they appear on the Contributor screens only after the Go to Production process
is completed.

Important: If targeting the production application, the link changes the data, even if the user has
submitted data.
When you run an Analyst>Contributor link that targets a development application, the data is read
out of Analyst when you run the D-Link. When you run the Go to Production process in the Con-
tributor Administration Console, or through Automation, the prepared data is written directly to
the import queue in the data store for the Contributor application as a prepared data block, e.List
item by e.List item.
There may be a delay between the Go to Production process and the data being reconciled in the
Web client. If, in the meantime, a planner edits one of the cells targeted by the link, that cell is
overwritten during reconciliation. This behavior is very similar to the reconciliation that takes place
when you import data into Contributor from text files or using DTS.
When you run an Analyst to Contributor link that targets the production application, the data is
read out of Analyst when you run the D-Link. An automatic activate process is run that applies the
data to a cube. If running the link using macros, you must run the @DLinkActivateQueue macro.
Contributor>Analyst Links
When you run a Contributor>Analyst link, the following occurs:
● A snapshot is taken of the production version of the Contributor Application.
To ensure a consistent read if you are using the @SliceUpdate macro, take the Contributor
application offline, or use the @DLinkExecuteList macro.
● A publish job is created and immediately set to ready.
Note that the job is not run, because the Contributor job executor is not used. Analyst transfers
the data.
● A Contributor session is loaded and the entire data block is loaded for each e.List item.
If the link is set up for more than one e.List item, it is equivalent to loading a multi-e.List item
view which is very memory intensive.
● The data is written directly to the Analyst cube data file (H2D file).
Contributor>Contributor links
These links go from the production version of a Contributor source to either the development or
production version of the Contributor target.
They are typically used between separate applications. If the applications are small, Contributor>Con-
tributor links can be fast. However, if you transfer data between larger applications this way, you
may run into problems due to memory use and scalability problems. You can avoid these issues by
using the @SliceUpdate macro. It can be more effective to use administration links in the Contributor
Administration Console, which copy data between Contributor cubes and applications. This process
is scalable and can move large volumes of data into either the development or production version
of the Contributor application.
Chapter 21: Analyst Model Design Considerations
Administration Guide 349

Chapter 21: Analyst Model Design Considerations
Copying AnalystContributor Links
Save As Method
Library Method
There are three methods for making copies of links. Save As, Library Objects, and Library Copy
Wizard. These three methods of copying AnalystContributor links affect whether the link refers
to the original application or a new application.
This method results in a copy which refers to the original Contributor application(s) and/or Analyst
D-Cubes.
Steps
1. In Analyst, open the link.
2. From the File menu, click Save As.
3. Choose a Library in which to copy the link.
4. Enter a name for the link copy.
5. Click OK.
This method lets you select the link with or without other objects and choose either to copy or
move the link. This results in a link which refers to the original Contributor application(s) although
the source or target Analyst D-Cube (if it is not a Contributor > Contributor link) could be changed
by this method if certain reference options are chosen when copying.
Steps
1. In Analyst, from the File menu, click Library, Objects.
2. Select the link with or without other objects and move it down.
3. Click the Copy selected objects button.
4. In the Copy dialog box, enter a new name for the link, select a target library in which to copy
the link, and select how to remap references.
5. Click OK.
Library Copy Wizard Method
350 Contributor
This method lets you make a copy of an AnalystContributor link which refers to a new application
based on a copied library.
Things to Watch Out For
● Using the Library Copy wizard to create duplicate objects within the same library will not work
for making copies of links because if you copy template D-Cubes containing the e.List, and
include the e.List itself in the selection of objects, the e.List will be copied. Thus when you
synchronize Contributor, the new cube you have created will be an assumption cube as it does
not contain the original e.List.

● A link can only be pointed to an application where it will refer to template cubes which were
copied at the same time. You cannot copy a link into a library which already contains suitable
template cubes and then refer the link to an application based on that library.
● If you make a copy of a link using this method and copy the link and its associated objects at
the same time, then you will not be able to refer the link back to the original application. You
will have to make a new application based on the copied library and refer the link to this new
application.
● If you copy macros which refer to Contributor applications using the Library Copy wizard,
Steps
then the macros will continue to refer to the original application. You must open the copied
macros and manually edit them to refer to any new applications based on copied libraries.
1. Use the Library Copy wizard to copy the link and any related Analyst template cubes at the
same time.
2. Create a Contributor application based on the copied Analyst template D-Cubes.
3. Point the link to your new application by using one of two ways.
Links and Memory Usage
● Open the link and then select your new Contributor application when prompted.
● From the File menu, click Library, Object. Double-click the link to move it down and then
right click the link and select Change Contributor source on D-Links.
The following factors affect memory usage when transferring data using links:
● the density of data
● the available RAM
● the use of multi-e.List item views with access tables, the size of which are not decreased as much
as single e.List item views.
● the maximum workspace setting (MAXWS) in Analyst
This is the amount of space reserved for Analyst. As a general rule, this should not be more than
half the available RAM. If you set this option too high the Analyst process can use so much memory
that it does not leave enough for the Contributor process.
Update a Link from a Computer That Cannot Access the Original Datastore
If a Contributor cube is used as a source or target, and the link is opened from a computer that
cannot access the original datastore, you are prompted to reselect the connection and application
to point to the data store and application name that holds the cube the link was built on. All
matching is then preserved. Save the link so it will run in the future.
Multiple data sources can be used. If two applications are built from the same Analyst library, the
GUIDs match when pointing the link to the original data store.
Chapter 21: Analyst Model Design Considerations
Administration Guide 351

Chapter 21: Analyst Model Design Considerations
To run a link from a workstation that does not have access to the original datastore you must
manually open the link and reselect the connection. You can also update the connection for several
links at once.
Steps
1. From the File menu, click Library, Objects and select one or more links that you want to update
and move then to the bottom pane.
2. In the bottom pane, right-click and click Change Contributor Source on D-Links.
3. Enter the connection details for the new data store.
4. Select the appropriate substitution option.
This updates all the selected links with the new connection details.
Multiple D-Links Using the @DLinkExecuteList Macro
@DLinkExecuteList is a macro designed to run a series of D-Links in order.
The @DLinkExecuteList macro behaves similarly to a series of @DLinkExecute steps, with a subtle
difference when D-Links have Contributor as a source. When the macro runs the first D-Link that
has Contributor as a data source, it logs the time and reads the database. All subsequent D-Links
that have the same Contributor source use the same data. This ensures consistency across D-Links
coming from the same Contributor data source. If a subsequent D-Link in the macro or submacro
has a different Contributor data source, the old source is closed and the new one is opened.
Run D-Links While Making Model Changes
Example
352 Contributor
If you want to make changes to the Contributor model and import data into Contributor using
Analyst>Contributor D-Links, synchronize first and then run the D-Link. For instance, if you have
inserted a new product as part of a model change, you cannot import data into the new product
until the Contributor model is synchronized. You must then run Go to Production to activate the
model and data changes.
You can use Contributor>Contributor links to preserve data during cube dimensional restructuring,
like when adding a dimension.
Steps
1. Take the Contributor application offline.
2. Run a link from the production version of the Contributor application to the import queue of
the development application.
3. Run Go to Production.

Effects of Fill and Substitute Mode on Untargeted Cells
Example Table One
In ContributorAnalyst D-Links, Fill and Substitute Modes behave the same way as standard D-
Cube to D-Cube D-Links in Analyst.
Fill and Substitute modes generally apply only to lookup and accumulation D-Links. In Substitute
mode, the data in the untargeted area of the D-Link remains unchanged. In Fill mode, the untargeted
cells are set to zero when the D-Link is run.
However, this applies only to lookup and accumulation D-Links. In standard D-Links, if an item
is not included in the right side of an allocation table, the original target data is unchanged,
regardless of whether you use Fill or Substitute mode. Similarly, on normal real dimension pairings
that use match descriptions, unmatched items are unchanged when the D-Link is run.
In Contributor, for a lookup or accumulation link that targets both detail and calculated items at
the same time, the zeros to fill and the data to set are merged into a single update of the target cube.
In Analyst, for lookup and accumulation D-Links, any cell within the target area of the cube is set
to zero if no data exists in the source cube for that cell. The fill is applied first to zero the data, and
then the data is written as if in substitute mode.
The different methods for Fill for Analyst and Contributor causes different breakback behavior to
occur. If the Analyst method is required for Contributor, you can use one link to zero the data,
then an accumulation link running in substitution mode.
The following table shows the action applied to untargeted cells for different types of D-Links when
a D-Cube or Contributor is the cube source.
D-Link type
Allocation Tables
Lookup
Example Table Two
Accumulation
Match descriptions
Fill
Keep
Zero
Zero
Keep
Substitute
Keep
Keep
Keep
Keep
The following table shows the action applied to untargeted cells for different types of D-Links when
a file map (ODBC or ASCII) is the cube source.
D-Link type
Allocation Tables
Lookup
Fill
Keep
Not Applicable
Chapter 21: Analyst Model Design Considerations
Substitute
Keep
Administration Guide 353

Chapter 21: Analyst Model Design Considerations
D-Link type
Accumulation
Match descriptions
Fill
Not Applicable
Zero
Effect of Access Tables in Contributor
354 Contributor
Substitute
Keep
If Contributor is the source, cells marked as No Data are treated as zero when running a D-Link
into an Analyst or Contributor target D-Cube.
If Contributor is the target, you cannot target No Data cells as defined by Access Tables in Contrib-
utor. However, as the Administrator, you are not subject to the restrictions imposed on Contributor
users entering data using the Web client. You can write to these cells just as you can using normal
import routines.

Appendix A: DB2 UDB Supplementary Information
This section provides an introduction to the IBM Cognos 8 Planning - Contributor for administrators
with responsibility for DB2 Universal Database (UDB) databases within the large enterprise,
specifically IBM DB2® Universal Database (UDB) version 8.1 for UNIX/Windows/Linux.
It assumes a familiarity with the tools provided by the database and a knowledge of security and
backup practices within the enterprise.
The Contributor Datastore
The implementation of a Contributor datastore is database specific: on DB2 UDB each application
exists as a separate schema.
The following table conveys the database terminology used throughout this section and the DB2
UDB equivalent.
IBM Cognos 8 Planning
terminology
Datastore server
Datastore application
Publish datastore
Description
The location where one or more data-
store applications are stored.
The container that holds the datastore
objects for the Contributor application,
such as tables.
A datastore container to which a Con-
tributor administrator publishes data.
DB2 UDB equivalent
Database
Schema
Schema
Requirements for the DB2 UDB Database Environment
Consider the following requirements when creating a DB2 UDB database environment for IBM
Cognos 8 Planning data.
● For DB2 UDB the target database for any operation must have been created beforehand by a
database administrator (DBA). We recommend that you create a new DB2 database to host
IBM Cognos applications. You may also choose to create a separate database to host Contributor
publish datastores.
Installed component
Contributor Server
Required client
DB2 Administration client
Administration Guide 355

Appendix A: DB2 UDB Supplementary Information
Installed component
Contributor Administration Client
Required client
None
● Connections are made to the IBM Cognos 8 Planning DB2 UDB database and all SQL statements
are fully qualified SCHEMA.TABLENAME.
For more information on installation requirements and procedures, see the IBM Cognos Resource
Center.
Background Information For DB2 UDB DBAs
Contributor has been designed to respect local enterprise database best practice. With the correct
permissions, Contributor will work without your intervention, creating and deleting tables. You
can also set up Contributor so that you can review, amend and execute DDL scripts against the
enterprise database. This is done using the Generate Scripts (GEN_SCRIPTS) option which may be
turned on or off.
Security and Privileges
356 Contributor
Specific operations in Contributor expect to issue data definition statements against the DB2 UDB
database. The user ID that is used to connect to the database to perform these operations must have
the appropriate privileges in DB2 UDB.
The privileges required for Contributor accounts are determined by setting the Generate Scripts
(GEN_SCRIPTS) option. Enterprise Planning Series components create schemas and tables and
populate them with data. Therefore users specified for connections must have been granted privileges
to create schemas and tables.
If you allow it, the Contributor application
● create and drop schemas
● create and drop tables
● create and drop indexes
● create and drop views
Alternatively, the application generates DDL scripts to do these things. You can then review the
scripts and execute them yourself. Additionally, Contributor needs to be able to bulk load data
using the DB2 UDB import utility, as well as carry out a non-logged delete of all data in a table.
When determining whether to generate DDL scripts, you may need to consider whether Contributor
should execute DDL against your enterprise database without review. You should also consider
whether local policy allows the Contributor security context sufficient privileges to be able to create
and remove Contributor datastores.
You may want to generate DDL scripts to comply with your own storage standards or to customize
storage clauses to take advantage of sophisticated enterprise storage. You may also want to amend
or add sizing clauses to the Contributor default DDL.

Naming Conventions
Metadata
Backup
Standards
Static object names are the same across all applications and do not change during the life cycle of
the Contributor application. Examples of static objects include the applicationstate table, which
contains the Contributor application definitions, and the history table, which log events and data
changes.
Dynamic objects, primarily the import tables and publish tables and views, are named after objects
within the Analyst model. Object names correspond to Contributor model object names with a
subsystem prefix. Examples of dynamic objects include im_cubename, which contains the import
staging tables.
During application creation, Contributor forces dynamic object names and Contributor application
datastore names to conform to the following conventions:
● only lowercase letters a to z and numeric characters are allowed
● no punctuation is allowed except for the underscore
The application datastore name defaults to the name of the Analyst library that is used to create
the application. Dynamic object names are based on the Contributor object name to which they
correspond, such as publish data is et_cubename.
Every Contributor datastore contains the metadata subsystem. The content of the metadata tables
is critical to the functioning of the Contributor application. The metadata provides a mapping from
internal Contributor model identifiers to the external database objects.
DDL scripts may be amended to conform to local storage conventions. You must not amend database
object names within the DDL script or allow the information contained within the metadata tables
to become out of sync with the underlying database objects.
Contributor does not back up data stored in the DB2 UDB database. You must back up the Con-
tributor datastore using tools supplied by other vendors. We do not anticipate problems restoring
from backups that use these tools, provided that
● the backup is taken of the whole datastore application (and the CM datastore?)
● no attempt is made to restore individual tables from backups taken at different times
All SQL is standard ANSI SQL and is executed via ADO / OLEDB.
The design of the datastore objects remove the need for complex table joins (the only place JOINs
are used is within the Reporting Views) and the few SORTs are typically on small result sets.
Data for transmission over HTTP (to and from the users entering the numbers into the model) is
compressed and stored as XML documents.
Appendix A: DB2 UDB Supplementary Information
Administration Guide 357

Appendix A: DB2 UDB Supplementary Information
Preventing Lock Escalation
By default, Contributor expects that DB2 will use row-level locking for concurrency control. Table
locking or any lock escalation may prevent Contributor from functioning normally. In particular,
operations, such as Validate Users and Reconcile do not work when table locks are applied.
Validate Users checks to see if users in the Web client have the rights to access the Contributor
data.
Reconcile ensures that the structure of the Contributor data is up to date in the Web client.
Steps
1. Set locks to default to row-level locking and try to avoid upgrading the locks to table-level
locking.
2. To prevent lock escalation, ensure that the LOCKLIST and MAXLOCKS settings are not too
small.
Large Object Types
Large object types (LOBs), binary large objects (BLOBs), and character large objects (CLOBs) are
used to store the XML documents comprising compressed data. Examples of this are the storage
of the model definition as well as user data for transmission over HTTP. In addition, users are able
to submit free-form comments or annotations which are formatted into XML documents and stored
as large objects.
You may have a policy on large object storage. The Contributor application allows you to specify
custom tablespaces for data, indexes, and large objects.
Alternatively, you can use the default tablespace, USERSPACE1.
We recommend that you store large objects within system-managed tablespaces. Projecting storage
and growth is essential to a successful long-term implementation. While most of the tables used for
Contributor datastores will grow and shrink, such as jobitem, other tables should be monitored
for growth, primarily nodestate.
Update of LOBS is via the OLEDB driver for DB2 UDB, IBMDADB2.
Notes: Currently, DB2 UDB does not use the buffer pool to manage LOBS. The datastores chosen
for tables containing LOBS should be placed in file containers that will be buffered by the operating
system.
Job Architecture
358 Contributor
For more information, you may want to refer to the IBM DB2 documentation on performance
considerations for LOBs.
Contributor operates a consistent and proven code stream across multiple database providers; that
is, a large proportion of the code (excepting database administration and DDL functions) is common
across different databases. The code is distributed within a classic n-tier architecture.
Data processing is carried out by job servers via the job architecture

Concurrency
A job may contain multiple job items which represent atomic items of work. Jobs are queued for
execution and picked up automatically.
A single-processor machine normally executes a single job item at a time. Job items are executed
by job servers.
Members of the job server cluster identify items of work by polling the job subsystem within the
Contributor datastore at regular intervals. Each job server continues to execute job items until no
more work exists. An individual job server may be asked to monitor one or more Contributor
applications. An job server may therefore be polling one or more Contributor datastores which
contain job subsystems within the Contributor environment.
The job architecture enables database administrators to limit the number of DML operations carried
out against the enterprise database by adding and removing job servers from currently executing
jobs.
Capacity Planning
UDB configuration parameters related to applications are dependent on the expected concurrency
on the database.
For IBM Cognos 8 Planning, database concurrency is a function of the number of job servers and
the number of threads per server. The maximum number of concurrent applications can be
determined by adding up all the active job tasks for all applications plus the epjobexec job itself
plus active connections for the Administration Console plus any run-time server side components.
Capacity planning and system sizing is dependent on model size and the number of Contributor
applications. Data volumes may grow during Publish. For more information, see "Reporting Data:
Understanding the Publish Job Process" (p. 359).
Importing and Reporting Data
Data is imported and published using two separate jobs: Import and Publish.
Existing planning data may be imported into IBM Cognos 8 Planning - Contributor import staging
tables (prefixed with im_). This functionality is supported for tab separated files via the Adminis-
tration console and uses the DB2 import utility.
Alternatively, you may choose a tool, such as IBM Cognos Data Manager to populate the tables
directly.
Whichever method you choose, the import data is processed and compressed by the Prepare Import
job and data is made available to web client users by the Reconcile job. The Prepare Import job
retrieves data from the datastore, processes it, and reinserts it into the application datastore in XML
format.
Reporting Data: Understanding the Publish Job Process
When publishing data, Contributor
Appendix A: DB2 UDB Supplementary Information
Administration Guide 359

Appendix A: DB2 UDB Supplementary Information
Data Loading
Job Failure
360 Contributor
● publishes to a separate datastore, where data expands from a compressed large object XML
format to a relational tabulated format
In this scenario, publishing data may require increased database processing resources. Tuning
logging, tablespace, and database parameters can help minimize the overall impact on your
database performance.
● using import load replace, truncates potentially large tables or large number of simple SQL
insert statements at start of job followed by a bulk load of data per node per cube plus
annotations
Logging needs to be monitored in this case to avoid a drop in performance.
The process of publishing data results in more storage being consumed because of how objects are
represented. While a conventional relational table can contain LOB columns, because the Publish
process uses LOBs to hold encoded data, which expands when transformed into simpler represent-
ations, storage requirements are increased further.
The administrator can limit the data to be published and limit the volume of data by adding a
publish data dimension.
Publish is broken up into units of work and processed via the job cluster. Data is uploaded using
the DB2 import utility.
Contributor supports options to accumulate all the data into large text files before uploading to
the target tables in the publish datastore. This is an interrupted publish. It does not reduce the size
of the publish data but it may fit more easily into enterprise procedures.
If an attempt at loading data fails because of inadequate disk space, the Publish job will cancel the
job. After you have allocated more tablespace, the Contributor Administration Console user should
attempt to run the job from the beginning.
If IBM Cognos 8 Planning fails to create a table during Publish then the next time Publish is run,
the application attempts to create a table again.

Appendix B: Troubleshooting the Generate
Framework Manager Model Extension
Use troubleshooting information to help solve problems you may encounter generating Framework
Manager Models.
Unable To Connect to the Database While Using Oracle
To correct an error message that Generate Framework Manager Model cannot find the correct
ODBC Driver (installed when you install Oracle), specify which Oracle ODBC driver to use in
Configuration Manager.
Note: Make sure you specify the Oracle driver and not the Microsoft ODBC Driver for Oracle.
Unable to Create Framework Manager Model
You may get an error message stating that you are unable to create a Framework Manager model
using the Framework Manager Script Player. A log file is created at installation_Location\
DOCUME~1\cognos01\LOCALS~1\temp\6\BMTReport.log.
This log file has two sections. The first section is the output generated using the Framework Manager
Script Player. The second part contains the actions that were executed.
Search on the word skip to see the errors in the log file.
In the Framework Manager Script Player section, look to see if the log file contains the following
error (the database values may differ):
Action: FindOrCreateDataSource failed, skipping…
Reason: QE-DEF-0285 Logon failure.
QE-DEF-0321 The userid or password is either missing or invalid.
QE-DEF-0068 Unable to connect to at least one database during a multi-database attach to 1
databases(s) in: test_sales_market_table
UDA-SQL-0031 Unable to access the "test_sales_marketi_table" database.
UDA-SQL-0129 Invalid login information was detected by the underlying database.
ORA-01017: invalid username/password; logon denied
This error has the following potential causes:
● The user running the Generate Framework Manager Model does not have access to the Signon
created for the data source connection.
● You are using Oracle or DB2 in a multi-computer environment and the configuration to access
the datastore is not configured in the same way on all computers.
Administration Guide 361

Appendix B: Troubleshooting the Generate Framework Manager Model Extension
Unable to Retrieve Session’s Namespace
You may receive error #CM-REQ-4159 stating that the session’s namespace cannot be retrieved.
This error may occur
● at the very end of the Generate Framework Manager Model process when the Finish button is
pressed and the system is trying to generate the Framework Manager model
● when testing the Gateway URL from Generate Framework Manager Model using a distributed
environment when the IBM Cognos 8 BI Server is on the same computer as IBM Cognos 8
Planning
To resolve this issue, delete the directory data source, and publish to a new container.
Steps
1. Stop and restart the services.
2. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administra-
tion.
3. On the Configuration tab, click Data Source Connection. Delete any directory data sources.
4. In Analyst, republish the data to a new publish container.
Unable to Change Model Design Language
362 Contributor
You cannot change the design language of the model that the Generate Framework Manager Model
Wizard creates. It is always English.

Appendix C: Limitations and Troubleshooting when
Importing IBM Cognos Packages
Use the following limitations and troubleshooting information to help solve problems you may
encounter when importing an IBM Cognos Package into IBM Cognos Planning.
Limitations for Importing IBM Cognos Packages
The following are the known limitations for importing IBM Cognos packages into IBM Cognos
Planning.
Aggregation of Semi-Additive Measures in SAP BW
The aggregation of semi-additive measures in SAP BW (aggregation exceptions for key figures in
SAP BW terms) is not supported in this release. An example of a semi-aggregate measure is anything
that can be classed as a movement, such as stock or headcount numbers. These measures can be
aggregated across some dimensions but not all.
These measures are fully supported by the IBM Cognos SAP BW OLAP provider when used on its
own. Except for some aggregations that are not supported in Framework Manager, semi-aggregate
measures in other OLAP providers and relational sources are supported.
Tips:
● Extract the measures via the OLAP interface in a separate Administration link.
● IBM Cognos Planning supports a wide range of aggregation types, for example, weighted
averages. You can load the leaf-level values from SAP BW into IBM Cognos Planning for
aggregation. This requires that IBM Cognos Planning is at the same level of aggregation as SAP
BW which might require a change to IBM Cognos Planning or SAP BW.
● If you have Data Manager installed, and have a good working knowledge of it, you can bypass
the Administration link and achieve the desired result for most aggregation types by moving
the data directly into the IBM Cognos Planning import tables.
Aggregation Support
SAP BW aggregation types that are not supported by Framework Manager, but that are supported
in IBM Cognos 8 queries by pushing the aggregation to the SAP BW system, are not supported by
the new IBM Cognos Planning access method for SAP BW.
Tip: You can load the leaf-level values and do the aggregation in IBM Cognos Planning where more
complex aggregations can be achieved, but there are some aggregations that cannot be replicated.
This also requires that IBM Cognos Planning is at the same level of aggregation as SAP BW which
might require a change to IBM Cognos Planning or SAP BW. You can alternatively use the OLAP
interface.
Administration Guide 363

Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages
364 Contributor
Administration Links Rows Rejected
It can be difficult to know which rows have been rejected or inserted by the Data Movement Service.
Tip: Switch the flag for writeContributorXML and writeDmsSpecOnSuccess from False to True in
the \Cognos\c8\bin\ dataimportserviceconfig.xmlTags file:
A generated file named: dmresult__.xml can be used to see records
that are inserted, updated, or rejected.
Administration Links with IBM Cognos Package as Source
Administration links that have an IBM Cognos package as the source can move data only into
Development, not Production.
Tip: Use Macros to run Administration links and add a Go to Production step to move the data
into the Production application automatically.
Administration Links and Marked Data
When two or more numeric Query Items are marked as data and mapped to the same target, the
data is not aggregated, instead two rows are delivered to the import table.
The import table itself takes the last entry as the loaded entry, so if there are two deliveries into the
import table for the same target cell, then the last entry is used. This is normal behavior for the
import table.
Tip: Remodel the data in the source or in Framework Manager to avoid this scenario.
Non-Numerics Marked as Data Mapping
Non-numeric Query Items, like text or dates, when marked as data in planning links, can only be
mapped as 1-1 in the manual mapping part of the links (both Administration and D-Links). Links
cannot have non-numeric Query Items marked as data in them at all if there are any 1 to many
mappings of marked data Query Items, even if only numerics are actually being mapped as 1 to
many. Only numerics can be in such links.
Tip: Create separate links for the numerics and non-numerics. If non-numerics need to be mapped
as 1 to many, then adapt the IBM Cognos Planning model to run the value in once and perform
the 1 to many mapping using D-Links. You can create multiple Administration links if the model
cannot be changed.
Framework Manager Model and SAP BW Usage Limitation
When using the SAP BW feature in IBM Cognos Planning, you can use only Single-Provider InfoCube
objects, not Bex Queries or InfoQueries.
Tip: There is currently no workaround for this except to use the SAP BW OLAP interface.
Framework Manager Expressions or Concatenations
Framework Manager Expressions such as concatenations or IF THEN ELSE statements do not
work across the OLAP and relational elements of the Framework Manager model, so a statement
cannot include references to both the relational and the OLAP parts of the Framework Manager
model.

Using BW OLAP Queries
If you use BW OLAP queries for IF THEN ELSE statements, then wrap string values in quotes and
do not use a mixture of string and numeric values in the same expression.
Multi-Provider SAP BW Cubes Not Supported
Multi-provider SAP BW cubes are not supported in the new SAP BW data access method for Plan-
ning.
Tips:
● Use the InfoCubes that underpin the multi-provider
● Create an InfoCube specifically for IBM Cognos Planning
● Use the IBM Cognos OLAP interface to SAP BW
Administration Link and Data Movement
Because of a limitation in the Data Movement Service, an individual Administration link element
(one query) can only run against one processor, so additional processors do not make an individual
link element perform better.
Tip: To improve performance, you may create separate link elements within a single link so when
the link executes, the link elements will be executed in parallel. Or you can create separate links
and run them in parallel.
Model Properties Not Automatically Updated
Model properties are not automatically updated when new objects are imported into the Framework
Manager model.
Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages
For example, if the model builder imports only some of the dimensions from a cube and then creates
a detailed fact query, and then imports additional dimensions, the new dimensions will not have
an important property set that is required by IBM Cognos Planning. The detailed fact query subject
does not have the correct properties set for the dimensions added after the fact query was created.
Tip: The workaround is to delete the detail fact query subject and recreate it.
Publishing Multiple InfoCubes in One Package
It is possible to have more than one InfoCube in a Framework Manager model and to run the
Detailed Fact Query Subject feature against each of them. It is then possible to publish the entire
model as a Package, IBM Cognos Planning can use the Package only if the IBM Cognos Planning
user uses metadata from one InfoCube per link.
Tip: Publish each InfoCube within a model in its own Package.
IBM Cognos Package Security
Only IBM Cognos Packages with an assigned database signon can be used with IBM Cognos
Planning since no log-on dialog box is displayed during import.
Administration Guide 365

Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages
SAP BW Hierarchies
Members in SAP BW hierarchies must have unique business keys, as assigned to the Business Key
role in Framework Manager, across all levels.
When working with SAP BW data, the Dimension Key field for any dimension should be hidden
in the Model (not the Package) - both for the OLAP and Detailed Fact Query Subject access before
the Package is published. It is not intended for direct use from within IBM Cognos Planning.
Query Prompts
Query Prompts defined in Framework Manager are not supported in any IBM Cognos Planning
links.
Tip: Change the model in Framework Manager.
SAP Variables Not Supported
SAP variables that generate Prompts in IBM Cognos 8 Business Intelligence are not supported by
IBM Cognos Planning.
Tip: Do not use the SAP variables when the package will be consumed by IBM Cognos Planning.
Troubleshooting Modeled Data Import
Use this troubleshooting information to help solve problems you may encounter when importing
data from an IBM Cognos Package.
You can troubleshoot modeled data import functionality in the following ways:
● Viewing generated files that contain information about errors
● Using error messages to troubleshoot
● Techniques to troubleshoot problems with an import
Viewing Generated Files
366 Contributor
There are several files available to help troubleshoot the Modeled Data Import functionality. All
of the files are written to your temp directory, usually: C:\Windows\Temp.
Some of the files are generated automatically, but for others you must activate the generation of
the files.
Files Generated Automatically
● _Result.xml. On link error it is not produced. On link success it is always
produced.
● _ImportFile.xml. Deleted by Contributor/Analyst if link is successful.
● .cmd. Deleted by Contributor/Analyst if link is successful.

Generated Files
Files Manually Activated
● contribXml_.xml. On link error: optionally by dataimportserviceconfig.xml; on
link success - optionally by dataimportserviceconfig.xml.
● dmspec__.xml. On link error: always; on link success -
optionally by dataimportserviceconfig.xml.
● dmresult_< adminlink name>_.xml. On link error: always; on link success -
optionally by dataimportserviceconfig.xml.
● dmrejected_< adminlink name>_.xml. On link error: optionally by dataimportser-
viceconfig.xml.; on link success - optionally by dataimportserviceconfig.xml. In both cases, the
file is written only if the switch is on and the link rejects rows.
Steps to Activate the Files
1. Open the dataimportserviceconfig.xml file in the bin directory. This file contains parameters
for the Modeled Data Import component.
2. Switch the flag from False to True for the following tags:
● writeContributorXMl
● writeDmsSpecOnSuccess
Setting the value to true will cause the file to be written when the import succeeds.
Note: For writeRejectedRowsToFile, if you set the flag to True, rejected rows will be written upon
a success or failure. If you set the flag to False, then no rejected rows will be written, whether there
is a success or failure.
Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages
By default, this file is saved in the temporary directory where Data Manager is installed. You can
change the location by changing the rejectedRowsFilePath using the syntax C:\\\\.
The following files are generated automatically to help you troubleshoot the import functionality.
.cmd
Used with _ImportFile.xml, this file can be used to rerun the import outside of
Contributor. This can be useful if it is unclear whether the Modeled Data Import is actually being
executed. Problems might be uncovered by running the import outside of Contributor. Double
clicking the file will execute it. By adding a pause command after the Java command inside the file,
the command file window will stay open until a key is pressed.
Example: testAnalystFileWrite1.cmd
This file is created by Contributor and Analyst, and is deleted after the Modeled Data Import
completes successfully. If the Modeled Data Import data fails, the file remains. The file contains
the commands and parameters to run the Modeled Data Import. It also contains a valid passport
that is only good until it expires. If the valid passport is copied along with .xml
while the import is occurring, a copy of the file can be used later. If the passport in a cmd file has
Administration Guide 367

Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages
Manually Activated Files
368 Contributor
expired, the expired passport can be replaced with a valid one. A valid passport can be taken from
a recently created cmd file.
_Result.xml
This file is used by Contributor to determine the success or failure of the import.
Example: TestCaseSap2_Result.xml
If the link executed successfully, this file contains a subset of the results contained in the dmres-
ult__.xml file. Also, if the dmrejected file (described above) is created,
this file will contain a message that lets you know where the dmrejected file can be found. Contrib-
utor reads this file to get the resulting status of the import. This file name doesn't contain a
timestamp. If the link failed, this file will contain a portion of the exception message that can be
found in the Planning error log.
_ImportFile.xml
Used with .cmd, this file can be used to rerun the import outside of Contributor.
This file is created by Contributor and Analyst, and is deleted after the Modeled Data Import
completes successfully. If the Modeled Data Import data fails, the file remains.
This file contains the commands and parameters to run the Modeled Data Import, information
about the matched dimensions, unmatched dimensions, data dimensions, and import table connection
info and column names.
The following files must be manually generated to help you troubleshoot the import functionality.
contribXml_.xml
This file can be used to check if Contributor or Analyst is producing a valid file for Modeled Data
Import. You can use this file to step through the Modeled Data Import code, if the model and cube
can be reproduced, or access to model and cube are provided.
Example: contribXml__Wed Jan 10 12_29_13 CST 2007.xml
This file contains the adminlink xml that the Contributor Application or Analyst model has sent
to the Modeled Data Import. It also contains information about the matched dimensions, unmatched
dimensions, data dimensions, and import table connection info and column names.
dmspec__.xml
This file can be validated against Data Manager's Data Movement Service schema to validate it for
well-formedness and proper content. It can also be used to create a Data Manager package. Packages
can be imported into the Data Manager user interface to be inspected and executed. Problems with
the spec can be discovered when creating the package and executing the package within the Data
Manager user interface.
Example: dmspec_TestCaseSap4_Wed Jan 10 12_29_32 CST 2007.xml. This file contains the Data
Manager's Data Movement Service spec file. These are the commands sent to Data Manager to
import the data from a source to the target.

dmresult__.xml
This result information, before it's written out, is used to create the _Result.xml
file. The _Result.xml file is a subset of the information in this file.
Example: dmresult_TestCaseSap4_Wed Jan 10 12_29_32 CST 2007.xml
This file contains the result of executing the spec in the Data Movement Service. If the import was
successful, the dmresult file will contain 'T' for the componentSuccess e.List node, the number of
rows read from the datasource, number of rows rejected, and the number of rows inserted into the
import table or written to the Analyst output file.
If unsuccessful, the dmresult file will contain either 'F' for the componentSuccess e.List node and
useful error message information, or no information at all.
dmrejected__.xml
This file is a raw output of rows that were rejected in processing the link within Data Manager.
These rows come directly from the datasource that the link reads. Rows are rejected when data
from the query items do not match expected target allocations in the target cube. For most data
sources, the rejected rows will contain data from the query items the link references, making
troubleshooting easier because, for example, the value in the rejected file would contain the
descriptions. However, for SAP Administration links where the Detailed Key Figures performance
enhancement is being used, the rejected rows will contain key values, not descriptions.
Example: dmrejected_TestCaseSap4_Wed Jan 10 12_29_32 CST 2007.xml
Using Error Messages to Troubleshoot
Occasionally import links will fail. Likely causes of these failures will be problems in interpreting
the model metadata when determining what should be imported, uses fields that aren't allowed in
links, or certain limits in xml parsing or data retrieval/filtering being exceeded.
When a failure occurs, error information is written to the PlanningErrorLog.csv file. Error messages
specific to the processing of the link itself will have "Admin Links Import" in the Component
column (regardless of whether Analyst or Contributor ran the link), "Data Import Service" in the
Source column, and the error message in the Error Description column.
The following error messages may occur when importing data from an IBM Cognos Package. View
the description and fix options for each error message to help you troubleshoot how to make the
link run.
Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages
Added Query Items with Concatenation in the Expression
Error Message: DS-DBMS-E402: COGQF driver reported the following:~~COGQF failed to execute
query - check logon / credential path~~DS-DBMS-E402: COGQF driver reported the following:
~~GEN-ERR-0015 Initially, in data source type(s) &amp;apos;BW&amp;apos;, function &amp;
apos;ces_concatenate&amp;apos; is not supported in &amp;apos;OlapQueryProvider&amp;apos;
. After decomposition, in data source type(s) &amp;apos;BW&amp;apos;,
Description: Query Items added to a Framework Manager model under a Query Subject that use
the concatenation functions ( '||' or '+') in the Query Item's expression are not supported in this
Administration Guide 369

Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages
370 Contributor
release. The query engine used to retrieve data when processing the link is not able to handle these
query items. It does not matter if the link is SAP or not.
Fix: Added Query Items with concatenation in the expression can be used within Analyst to build
D-Lists that can be included in a cube. However, these same query items cannot be used as a source
query item within a link in Analyst or Contributor. To get the appropriate mapping to occur when
choosing the source query items for the link, pick one of the query items used in the concatenation
expression. Then, when mapping to the target dimension that includes the concatenated values,
map the single source query item to the target dimension and use a sub-string on the target dimension
to achieve the appropriate mapping.
Expected ConformanceRef Not Found
Error Message: Error encountered in Modeled Data Import of the Data Import Service.~~Caused
by: java.lang.RuntimeException: Processing of this link has been aborted because the link contains
a mixture of query items with and without the metadata conformanceRef attribute.The conforaman-
ceRef attribute for query item [SottBwp1NikeBw].[Orders].[New Query Subject].[TestQueryItem]
can not be determined.This link will have to be run using a package that doesn't contain the Detailed
Fact Query Subject (aka Detailed_Key_Figures).~~~at
Description: ConformanceRef is a hidden Framework Manager attribute used to link the OLAP
query items to the relational query items and exists when the Detailed Fact Query Subject is created
for a SAP model. When processing a link with a SAP model that has the Detailed Fact Query Subject
created and a query item is discovered in the link that cannot be linked to the Detailed Fact Query
Subject, an exception occurs. Examples of this are if any query item in a dimension or the Key
Figures that has been added to the model since the Detailed Fact Query Subject was created, or if
a query item is added under a query subject folder.
Query items like this have an expression that pulls values from one or more dimension or Key Figures
values. These can never be linked to the Detailed Fact Query Subject. If the first query item of the
link can't be referenced to the Detailed Fact Query Subject, then the Detailed Fact Query Subject
won't be used for the entire link, and the link should run successfully. But, if a query item that can't
be linked to the Detailed Fact Query Subject is processed after one or more query items that can
be linked, then the link will fail.
Fix: Deleting and regenerating the Detailed Fact Query Subject and republishing the package will
fix query items added to the Key Figures or a dimension.
When dealing with query items added to a query subject, deleting and not regenerating the Detailed
Fact Query Subject, then republishing the package will allow the link to run. However, the added
query item can't contain an expression using concatenation.
Entity Expansion Limit exceeded
Error Message: com.cognos.ep.dataimportservice.modeleddataimport.ModeledDataImport.main
(Unknown Source)~~Caused by: org.apache.axis.AxisFault: ; nested exception is: ~~org.xml.sax.
SAXParseException: Parser has reached the entity expansion limit "64,000" set by the Applica-
tion.~~~at org.apache.axis.AxisFault.makeFault(AxisFault.java:129)

Note: The above error message occurred when the expansion limit was set to 64,000. The error
message would refer to 200,000 if a client were to encounter the error with the IBM Cognos default
setting.
Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages
Description: Framework Manager import uses the Java coding language when processing the link
information from Analyst or Contributor. Java XML parsers have a built-in default limitation on
how large an XML document can be. Exceeding this limitation will cause an exception to be thrown
and the link will fail. The Framework Manager import code provides a configurable override to
this limit. The Java limit of 64,000 has been increased to 200,000 by the override value. However,
it might be possible to build a link that exceeds this increased limit.
Fix: Open the dataimportserviceconfig.xml file located in the bin folder of the IBM Cognos
installation directory. Find the parameter with a name of "EntityExpansionLimit" and increase the
value. A suggested increase would be to make the value 300,000. Increasing the expansion limit
may mean that more internal memory will be needed, causing a out of memory problem if the
maximum heap size isn't also increased. Find the JavaMaximumHeapSize parameter and increase
that as well. Doubling the value to 256M should be safe for 300,000, but memory limitations on
the machine may still cause out of memory issues.
Too Many Filter Values
Error Message: ~DS-DBMS-E400: COGQF driver reported the following on connection &amp;
apos;3&amp;apos;:~~Unhandled Exception~~databuild -- failed
Description: There is a limitation on the number of filter values in the IBM Cognos query engine,
and exceeding that limit by building a query with a very large number of filter values causes the
link to fail. This can happen in Analyst when building a D-Link with one or more matched dimen-
sions mapping to large cube dimensions. It happens in Analyst or Contributor when the link contains
one or more unmatched source dimension that are filtered with a large number of values. It happens
in Contributor when the link contains one or more matched dimension manually mapped with a
large number of values. Look at the link itself to determine if the quantity of filters might be causing
the problem. The point where a problem occurs is somewhere around 300 total filter values. If this
error message is encountered, and the link deals with a large number of filter values, the fix
description below is the best way to get the link to run.
Fix: Open the qfs_config.xml file in the configuration folder under the IBM Cognos 8 installation
directory. In the provider e.List with the name of "OlapQueryProvider", add the following:
Save the file and restart the IBM Cognos 8 service.
Note: Turning this parameter on affects all queries, not just queries in Framework Manager links.
While performance may suffer when this is on, it can be turned off or removed from the configuration
file after the link has executed.
Comparing _businesskey With Random Values
Error Message: OP-ERR-0070 'Customer' can only be compared to actual values of the query item.
Filters referring to arbitrary string constants should be applied to attribute query items.
Administration Guide 371

Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages
Description: In the SAP models, each level in a hierarchy contains a query item that has a role of
_businessKey. This query item is not intended for use in links, and therefore should not be used.
This query item is a special field that contains specific key values. If the query item is compared to
values that are not in the field's domain of values, an exception is thrown.
Fix: Since these query items are not intended for use in links, they should be hidden from view in
the model (not the package) - both for the OLAP and Detailed Fact Query Subject access before
the package is published.
Techniques to Troubleshoot Problems with an Import
Perform the following techniques to troubleshoot problems with the modeled data import function-
ality.
Using Data Manager User Interface to Troubleshoot an Import Problem
372 Contributor
Perform the following steps to create a Data Manager package and import the package into the
Data Manager user interface.
Steps
1. Create a (.bat) file to convert the dmspec__.xml into a package
file
● The command in the .bat file is:
"Cognos
Installation Directory\bin\CatAdapterTest"
-x "D:\DMSpec\generatePkg\TestCaseSap4.xml" -p "D:\DMSpec\generatePkg\
TestCaseSap4.pkg"
where "D:\DMSpec\generatedPkg\TestCaseSap4.xml" is the dmspec file
to process and the "D:\DMSpec\generatePkg\TestCaseSap4.pkg" is the
resulting package file.This example shows the files have been
copied or renamed to an easier name to type. The path to the xml
and pkg files will have to match the computer’s directory structure.
● Following the above command with a pause command on the second line will leave the
command window open to view the package creation. This is useful if the package creation
fails so you can see messages.
2. Run the bat file. A (.pkg) file will be created if successful. If unsuccessful, error message on why
the package couldn’t be created will be displayed.
3. Open the Data Manager user interface, then open an existing catalog or create a new catalog.
4. Import the package file to create a build. From the File menu, click Import Package and navigate
to the package file that you just created. It is not necessary to backup the catalog.
From the package file, a new build will appear under the Builds and Jobstreams e.List. You
can click the new build to see a graphical representation of it.
5. Fix the Connection. The build will not run until the Framework Manager package has been
associated with the build's source connection and the target connection is correct.

● Click the new build and note the number of the source connection that appears on the very
left. Also, note the name of the target connection, on the far right of the build. This is
usually CON1, or something similar.
● Expand the Library/Connections e.List and find the corresponding connections.
● Right-click the source connection and click Properties. Click the Connection Details tab.
● Connection types will be selected on the left. Click Published Framework Manager Package.
On the right, the Package box will be empty.
● Click the … button. An IBM Cognos 8 logon window will appear. After that, a list of
published Framework Manager packages will appear and select the appropriate package
and click OK.
● From the Connection Properties window, click Test Connection to verify that the connection
is now good. Click OK.
● Right-click the target connection and click Properties, and then click Connection Details.
● Verify that the Connection Details are correct. Click Test Connection. Click OK to save
any changes.
● Click Save.
6. Highlight the build and click Execute. Even if the build is highlighted, it won't execute unless
it was the last thing clicked.
A command window will open showing the status and results of the build execution.
7. To determine problems with the v5 query, right-click the datasource icon in the build and click
Properties.
Select one row. Click the Query tab and click Run. Problems with the V5 will be displayed as
it tries to run.
Rerunning an Import Outside of Contributor
If the import fails, the cmd and _Importfile.xml will remain in the directory. If
the import succeeds, the two files will be deleted. If you want to re-run a successful import, you
have to copy the two files after the import starts, but before it ends. Remember, the cmd file contains
a passport. Once the passport expires or the C8 server is bounced, the passport is useless.
Note: Check the status of a INTER_APP_LINKS in the Administration Console. If the cmd file has
been deleted, the contents can be copied from the Failure Information dialog box.
Steps
Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages
1. Edit the cmd file and add a line at the end of the file that contains pause. This will keep the
command window open after the import finishes.
Another option is to redirect the cmd file output to a text file. Add >> c:\windows\temp\
linkoutput.txt to the end of the first line. This will redirect the output to the linkoutput.txt
file and can be viewed after the cmd file execution completes.
Administration Guide 373

Appendix C: Limitations and Troubleshooting when Importing IBM Cognos Packages
2. Save the changes.
3. Locate and double-click the cmd file to view the output from the import. Also, dmspec,
dmresult, and _Result files are created like when running within Contributor.
Keeping the Analyst Export File created by Data Manager.
Job Timeouts
374 Contributor
After a run loads data into an Analyst Cube, the temp file that is created by Data Manger is typically
deleted. If you wish to keep that file around for debugging purposes add a registry key called
DropExportFile in the Analyst settings registry folder, and set the value to 0 (zero).
An Administration link that executes for more than 30 minutes may appear to have timed out,
showing up as Cancelled in the Monitor Links section of the Administration Console.
Even though the execution of the link may have failed, you can look in Task Manager for dmrunspec.
There will be one for each link element in the link. If the Administration link is marked as failed
or cancelled - check for dmrunspec instances.
To increase timeouts you need to edit epJobExecutorResources.xml, located at \
cognos\c8\bin, and increase the value for Wait this long to see if RUNNING Job Items complete.
Default setting is 1800 (30 minutes). The file is installed as read-only. We recommend that you
back up the file and reset the read-only flag to writeable. After changing this setting, the Planning
service needs to be stopped and restarted on the machine that is executing the link.

Appendix D: Customizing IBM Cognos 8 Planning
- Contributor Help
This section provides extra information about creating information for planners and reviewers.
Creating Cube Help
Detailed Cube Help
You can create help for each cube. There are two types of help:
● Simple cube help: This is one line (the limit is 200 characters) of plain text only. This appears
at the top of the grid, below the tabs. For more information, see "Creating General Messages
and Cube Instructions" (p. 78).
● Detailed cube help. This appears as a separate web page when the user clicks the Help button
at the top of the grid. This is described in the following sections.
The administrator writes the help text either in plain text, or using HTML formatting.
You can customize the format of the detailed cube help using HTML text formatting (p. 375). If
you choose to use no formatting, the help will display in a standard format.
After the Contributor application has been made live, the user has opened the Contributor applic-
ation and loaded the grid, the user accesses the cube help by clicking the help button at the top of
the grid.
If you do not write any help for the cube, it will default to the default Contributor browser help.
Using HTML Formatting
Sample HTML text
Use basic HTML tags to apply text formats to text in Instructions. In addition to formatting text,
tags can be used to include hypertext links and images.
Some basic rules for using HTML text tags:
● Text tags are used in pairs with the text they alter between them. For example, my text
here.
● A start tag consists of a left and right angle bracket, with a tag name in between. For example,
.
● An end tag consists of a left and right angle bracket, a tag name, and a forward slash. For
example, .
Sample Help Text
2nd heading level
Administration Guide 375

Appendix D: Customizing IBM Cognos 8 Planning - Contributor Help
376 Contributor
3rd heading level
This is a paragraph.
This is a paragraph with a hyperlink to the Cognos web site
This is a paragraph with a sample e-mail link to E-
mail technical support.
This is the first numbered list item.
This is the second numbered list item.
This is the third numbered list item.
This is another paragraph.
This is a bulleted list item.
This is another bulleted list item.
Help text
Sample Help Text
This is a paragraph.
IBM web site
E-mail technical support
Description
indicates the start of text that is displayed
in heading 1 style.
Sample Help Text is the text that is displayed
in heading 1 style.
indicates the end of heading 1.
Indicates the start of a paragraph.
Indicates the end of a paragraph.
This is a hypertext link. For more information,
see "Creating Hypertext Links" (p. 377).
This is an email link. For more information, see
"E-mail Link Example" (p. 378).

Help text
This is the first numbered list item.
Description
This is a numbered list. The tag indicates
the start of an ordered list and indicates
the end of the ordered list.
This is the second numbered list item. indicates the start of a list item and
This is the third numbered list item.
This is a bulleted list item.
This is another bulleted list item.
indicates the end of a list item. You can have as
many list items as needed between the and
tags.
This is a bulleted list. The tag indicates the
start of an unordered list and indicates
the end of the unordered list.
indicates the start of a list item and
indicates the end of a list item.
Using Images, Hypertext Links, and E-Mail Links in Contributor Applications
In Contributor Help Text, you can enter instructions that appear to users in the Contributor
application.
Adding images to instructions
You can add images in .jpg or .gif format to instructions, for example, a company logo.
Steps
Creating Hypertext Links
1. Create a folder for images in the same directory that you have used for the web site.
2. Reference the graphic in the following way:
3. You must use the full path to reference the image, otherwise it will not display to all users.
You can use hypertext links to allow users to jump from a Contributor application to other web
pages. You can put links in Instructions and Cube Instructions.
Example
To link to a file named File.html located in the subdirectory Path found on the server www.ibm.com,
you enter the following:
Appendix D: Customizing IBM Cognos 8 Planning - Contributor Help
text or image
Administration Guide 377

Appendix D: Customizing IBM Cognos 8 Planning - Contributor Help
E-mail Link Example
378 Contributor
You can use e-mail links in Planning Instructions and Cube Instructions to allow users to e-mail
someone directly from the Contributor application. When they click the e-mail link, your default
e-mail tool is launched.
Example
To add a link to your technical support contact, you could use:
E-mail technical support
This will appear in a manner similar to this in the Web browser:
E-mail technical support

Appendix E: Error Handling
This section covers the following areas:
● How IBM Cognos 8 Planning - Contributor tracks problems, and information on the files you
may be asked to provide to IBM Cognos Resource Center.
● How to use the epLogfetcher to locate and retrieve different error logging files.
● Timing and logging registry - timing and logging provides timing for processes. This is written
to a file named PlanningTraceLog.csv, which is in the same locations as the PlanningErrorLog.
csv file and is useful for troubleshooting.
Error Logs and History Tracking
This section describes the different ways in which Contributor tracks problems, and describes the
files you may be asked to provide in order to resolve them.
You may be asked to supply a number of different files to IBM Cognos Resource Center, depending
on the nature of the problem.
Type
Application XML
History tracking
Administration
Console History
tracking
JCE error logs
Description
Contains details about
the Contributor applica-
tion. Can represent the
Development or Produc-
tion model.
Tracks actions per-
formed by users.
Tracks actions
performed via the
Administration
Console/Job system.
Errors with the calcula-
tion engine.
Location
User Defined.
Database table named
history.
Database table named
P_ADMINHISTORY.
Job server, administra-
tion machine or client
machine on the local
Temp folder
(%TEMP%)
File name
applicationname.xml
Not applicable
Not applicable
jce*.tmp
Administration Guide 379

Appendix E: Error Handling
Type
General Error logs
Logging and tim-
ing
Description
Errors in the Administra-
tion Console.
Provides timing for pro-
cesses, and verbose log-
ging.
Location
Local Temp folder
(%TEMP%), on
administration
machine, web server
or client.
Local Temp folder
(%TEMP%), on
administration
machine, web server
or client.
These files are described in more detail in the following sections.
Application XML issues
Timeout Errors
File name
PlanningErrorLog.csv
PlanningTraceLog.csv
Details about the Contributor application are held in XML format. If there are problems with a
Contributor application, you may be asked by IBM Cognos Resource Center to save the XML as
it is at that particular state and send the XML file. You can save the state of both the development
application and the current production application.
See "Save Application XML for Support" (p. 79) for more information.
If you are experiencing timeout errors on long running server calls. Change the default remote service
call timeout value (default 480 minutes) to allow for longer calls.
Steps
1. On the System Settings page, click the System Settings tab.
2. Change the default call timeout to allow for longer calls.
For information about the Maximum e.List items to display as hierarchy options, see "Import e.List
and Rights" (p. 96).
History Tracking
380 Contributor
The history tracking feature in Application Options (p. 74) tracks the actions performed by users.
When you have Actions timestamps and errors, or Full debug information with data selected,
information is recorded in the database in a table named history.
You can use history tracking if you have problems with, for example:
● Workflow - in which case you set history tracking to Actions timestamps and errors.

● Aggregation (if it appears that you have incorrect aggregation), you should set it to Full debug
information with data.
The actionid contained in the history table is made up of two codes: a result code and an action
code. The first 2 digits are the result code and the rest make up the action code.
The following table shows the result codes and their meanings.
Result Code (Hexadecimal)
00
01
02
03
04
05
06
07
08
09
0A
0B
0C
Result
Success
Not Owner
Being Edited
Data Changed
Annotation Changed
Locked
Not Locked
Not All Children Locked
Annotation Backup Failed
Data Backup Failed
Grantor Locked
Already Reconciled
Not Initialized
The following table shows the Actionid from the history table and the action that it refers to. Note
that sometimes actionids may be combined. For example, if a user has made a change and submitted,
you might get the Actionid oxo4Ao.
Actionid (Hexadecimal)
0x0000
0x0001
0x0002
Action
None
Get Data
Get Annotations
Appendix E: Error Handling
Administration Guide 381

Appendix E: Error Handling
Actionid (Hexadecimal)
0x0004
0x0008
0x0010
0x0020
0x0040
0x0080
0x0100
0x0200
0x0400
0x0800
0x1000
0x2000
0x4000
0x8000
Action
Get Import Block
Annotate
Edit
Save
Start
Submit
Reject
Reconcile
Release
Take Offline
Bring Online
Check Data Up To Date
Update
Edit If Owner
See "Change Application Options" (p. 74) for further information.
Calculation Engine (JCE) error logs
382 Contributor
JCE error logs can be found either on the Web server, the Administration Console machine,
administration server, the job server, or the client. They only appear on the client when there have
been problems using the Web browser.
You may get a server side JCE Error log in the following circumstances:
● If the Administration Console crashes
● Problems when importing the e.List
● Problems during import
● Problems during the Go to Production process
● Problems during synchronize

● Problems during publish
This is not an exhaustive list, and you may get an error message telling you that a log was created.
To search for a JCE error log, search for JCE*.tmp.
These log files are stored in hidden folders.
General Error Logging
Most areas of the application log their errors to a file named PlanningErrorLog.csv. In Windows
NT4, this is stored in the Temp directory. In Windows 2000, it is normally be found in:
Documents and Settings\user name\Local Settings\Temp\
These logs can be created on the client, the Administration Console machine, administration server,
web server, or the job server. Most components and applications log to this file including IBM
Cognos 8 Planning - Analyst.
How Errors are Logged in the Administration Console
Errors that occur in the Administration Console are logged to help bug tracking.
Due to the distributed nature of the execution of Contributor, it is also necessary to distribute the
error handling/logging. For example, it does not make sense to log all the errors on the users’ web
client for errors that happen on the web server.
The logs created by components are put on the machine on which they execute.
The log file created is in tab separated format, but it has a .csv extension so that it automatically
loads into Excel when it is double clicked (if Excel is installed). Excel 97 gives you a warning that
the format is not recognized, but actually opens the file without any problems. Opening the file in
Notepad makes it difficult to read as the columns do not align due the varying length of the log
entries. If the log cannot be written, for example, the file is locked by another process, or is read-
only, then the log entry is written to the NT event log (if it exists) and the application fails with a
message saying that logs cannot be written. If no log is written for a long time, the application can
continue to execute even if the logging would cause problems in the future - this is normal "on
demand" resource usage as recommended by Microsoft.
During execution you may get an error that passes through multiple components as it works its
way up the call stack. In this case there will be entries in the log for each procedure that is affected
with a line number. For errors to be traced correctly, we need the log for each machine and user
context affected by the error. This can be difficult if you do not know where all the code is
executing, so it is advisable to send technical support all the logs you can find. We can usually tell
if there is a log entry missing from the identity information that is associated with each error.
An error log contains the following fields:
Appendix E: Error Handling
Administration Guide 383

Appendix E: Error Handling
384 Contributor
Field Name
GUID
Stack
Date Time
Component
Module
File
Version Information
Procedure
Line Number
Source
Error Number
Error Description
Description
Each distinct error has a unique GUID (a unique identifier)
by which it is identified. By looking at entries in the log
with matching GUIDs it is possible to group log entries by
particular errors. It is possible to cross reference errors
between different log files if the error stack spans server
side and client side components.
This is used in conjunction with the GUID to determine the
source of the error, and the call stack that the error was
passed through before being reported. A value of 1 indicates
the source of the error, and the highest value is the point
at which it was reported to the user. Again these sequences
can span log files.
The date and time at which the error occurred. The time is
taken from the machine where the component represented
in the current log entry is running.
The name of the component represented in the current log
entry.
The code module in which the error occurred.
The source file name.
The version of the component represented in the current
log entry.
The procedure within the file where the error occurred.
The line number within the procedure where the error
occurred. This enables a developer to trace exactly which
call caused the error, and in conjunction with the error
number and error message, it gives a high degree of detail
about the problem.
The origin of the error. May or may not be within IBM
Cognos components.
The identifier for the error condition.
A description of the error which has occurred.

Field Name
User Domain/User Name
Machine Domain/Machine Name
Previous User Domain/ Previous
User Name
Previous Machine Domain\ Previous
Machine Name
Process ID
Thread ID
Description
The User Domain/User Name under which the component
represented in the current log entry was executing.
The Machine Domain/Machine Name on which the
component represented in the current log entry was
executing.
The domain on which the user was logged into and the
previous user name.
The machine from which the call was made to the current
component. This is the indicator to go and look for error
logs on this machine, where it may be possible to find cor-
responding entries (matched on GUID), lower down the
call stack. It may also provide clues to other errors that
occurred prior to the issue being investigated.
The current process ID.
The current thread ID.
It is imperative that these logs are provided to development when reporting problems.
Using the LogFetcher Utility
The LogFetcher utility should only be used on the advice of IBM Cognos Resource Center.
The LogFetcher utility retrieves planning log files from multiple machines. It retrieves the following
logs:
● PlanningErrorLog --for general errors. This is typically the first log you would look at if you
have a problem.
● PlanningTimer--for timer files. These files will be present if timing has been enabled (see below.)
● AnalystLog--Analyst errors.
● IISLog--Web connectivity or download problems.
● JLog--J server errors. It contains errors relating to data, links, and calculations.
Steps
1. Run epLogFetcher.exe from installation_location\Cognos\c8\bin\
2. Right click in the top panel and click Add.
3. Enter the search criteria for the log files:
Appendix E: Error Handling
Administration Guide 385

Appendix E: Error Handling
386 Contributor
Criteria
Machine to Search (or IP
Address)
Select Protocol
File to retrieve
Working Folder
Description
Enter the machine name or IP address with the log files.
To search the local machine, enter localhost.
Select HTTP if you are looking for components on the
Administration server.
Select COM if your Administration Console is on a sep-
arate machine to the Administration server and you are
searching locally Check - was MTS server.
Select one of the following:
PlanningErrorLog
PlanningTimer
AnalystLog
IISLog
JLog
Enter or browse for a folder to retrieve the files to on
your local machine.
4. Click Add. This adds the search criteria to the top panel. Repeat steps 2 to 4 until you have
added all the log files you need.
5. To start the search, select the lines containing the search criteria and click View File(s).
Tip: You can do this one line at a time, or you can select multiple lines by holding down CTRL
and clicking. The results of the search are displayed in the lower panel.
6. In the lower panel select the files you want to bring into the working folder and click Get File(s).
If you select two or more files with the same name into the same working directory, a number is
appended to the file name.
This tool only finds IIS logs if they are in the default path. It is not capable of retrieving logs from
remote client machines.

Appendix F: Illegal Characters
The following ASCII characters are not allowed as e.List item and user names, e.List item and user
captions, user logons and user email.
They are also not allowed in dimension names or in namespace names.
Note that these are non-printing characters below ASCII code 32.
Decimal
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Char
NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
TAB
LF
VT
FF
CR
SO
SI
DLE
Description
Null
Start of heading
Start of text
End of text
End of transmission
Enquiry
Acknowledge
Bell
Backspace
Horizontal tab
NL line feed, new line
Vertical tab
NP form feed, new page
Carriage return
Shift out
Shift in
Data link escape
Administration Guide 387

Appendix F: Illegal Characters
388 Contributor
Decimal
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Char
DC1
DC2
DC3
DC4
NAK
SYN
ETB
CAN
EM
SUB
ESC
FS
GS
RS
US
Description
Device control 1
Device control 2
Device control 3
Device control 4
Negative acknowledge
Synchronous idle
End of transmission block
Cancel
End of medium
Substitute
Escape
File Separator
Group Separator
Record Separator
Unit Separator

Appendix G: Default Options
Grid Options
The following sections describe the default options for a Contributor application.
In the Grid Options, you can set the following:
Option name
Set breakback option
Saved data
Typed data not entered
Data entered but not saved
Allow multi e.List item views
Allow slice and dice
Recalculate after every cell change
Application Options
In Application Options you can set the following:
Option name
History tracking
Cut-down models
Allow reviewer edit
Allow bouncing
Prompt to send email when user takes owner-
ship
Use client-side cache
Default
All cubes on
Black
Green
Blue
Off
On
Off
Default
Action time stamps and errors
No cut-down models
Off
On
Off
On
Administration Guide 389

Appendix G: Default Options
Option name
Prevent off-line working
Prompt to send email on reject
Prompt to send email on save
Prompt to send email on submit
Web client status refresh rate
Record Audit Annotations
Annotations Import Threshold
Annotations Paste Threshold
Display Audit Annotations in Web Client
XML Location and Filename
Default
Off
On
Off
Off
5 minutes
Off
0 (all rows imported in a single transaction are
recorded as a single entry)
0 (all rows pasted in a single transaction are
recorded as a single entry)
This defaults to the local temporary directory and the name of the Analyst model used to create
the application.
Admin Options
390 Contributor
You can configure the import and publish actions using the following options:
Option name
Datastore Version Number (DB_VERSION)
Import Block Size (IMPORT_BLOCK_SIZE
Import Location (IMPORT_LOCATION)
Import Options IMPORT_OPTIONS)
Publish Options (PUBLISH_OPTIONS)
Optimize Publish Performance
Off
Default
-1 (All)
Blank
Blank
Blank
Manage Indexing

Option name
Generate Scripts (GEN_SCRIPTS)
Table Only Publish Post-GTP (POST_GTP_
TABLE_PUBLISH)
Act as System Link Source (LINK_SOURCE)
Display warning message on Zero Data
Base Language
Scripts Creation Path
Default
No (for DBA). Note that if the DBAuthority
key is set to USER, in the datastore,
GEN_SCRIPTS will be set to true.
No
No
No
EN
Blank
Note that Admin Options are not visible to users when the DBAuthority key is not set to DBA in
the registry.
Go to Production Options
You can set the following options prior to creating the production application:
Option name
Prevent Client-side reconciliation
Copy development e.List item publish setting
to production application
Planning Package
Name
Screen tip:
Description:
Overwrite the package access rights at the next
Go To Production
Go to Production Wizard Options
Default
Off
On
Name of the Package
Blank
Blank
On
You can set the following Go to Production Wizard options:
Appendix G: Default Options
Administration Guide 391

Appendix G: Default Options
Option name
Back-up Datastore
Display invalid owners and editors
Create Planning Package
Workflow States: Leave
Workflow States: Reset
Publish Options-View Layout
Default
On
Off
On
On
Off
You can set the following options to set the View-Layout publish options and configure the publish
datastore connection:
Option name
Publish Datastore
Do Not Populate Zero/Null/Empty Data
Publish only cells with writable access
Use plain number formats
Remove all data before publishing new data
Include user annotations
Include audit annotations
Publish Options-Table Only Layout
392 Contributor
Default
No Container Set
On
Off
On
On
On
Off
You can set the following options to set the Table-Only Layout publish options and configure the
publish datastore connection:
Option name
Publish Datastore
Create columns with data types based on the
‘dimension for publish’
Default
name of publish datastore
On

e.List
Rights
Option name
Only create the following columns
Include Rollups
Include zero or blank values
Prefix column names with data type
Include User Annotations
Include Audit Annotations
Include Attached Documents
Default
When importing the e.List with just the compulsory columns in the file, you get the following
defaults:
Option name
Publish
View Depth
Review Depth
Access Tables
Off
On
Off
On
On
Off
Off
Default
When importing rights with just the compulsory columns in the file, you get a default of Submit.
No
All
All
If no access levels are set, the following defaults apply:
● All cubes apart from assumptions cubes have a global access level of Write.
● Assumption cubes (cubes used to bring data into an application) have a global access level of
Read.
The following rules apply for an imported access table.
Appendix G: Default Options
Administration Guide 393

Appendix G: Default Options
Option name
Name of e.List
AccessLevel
Default
Applies to the whole e.List if omitted.
No Data.
The base access level for rule based access tables is Write.
Delete Commentary
394 Contributor
You can set the following options:
Option name
Delete user annotations
Delete audit annotations
Delete attached documents
Delete annotations before
Delete any annotations containing text
Default
Off
Off
Off
Off
Off

Appendix H: Data Entry Input Limits
The data entry limits for IBM Cognos 8 Planning - Analyst and IBM Cognos 8 Planning - Contributor
are affected by a number of different factors. Limitations may be imposed by a number of different
factors such as operating system, datastore provider, and computer hardware.
Note: The limits described here are guidelines, and are not hard and fast rules.
Limits For Text Formatted Cells
The data entry limits for text formatted cells for Analyst, Contributor Browser, and the Analyst
for Excel are 32K (32,767 characters). Note however that in some cases, further limits are imposed
by the datastore provider.
For Contributor for Excel, the maximum number of characters is 911. Special characters, like
Returns and Tabs are not supported. If you need to copy and paste multiple paragraphs of text into
a cell from another document, ensure that you remove the returns after each paragraph before you
copy and paste text into a cell. Otherwise Contributor for Excel will truncate the incoming text
after the first paragraph.
For annotations, the maximum number of characters are 3844 characters. For attached documents,
the maximum number of characters in the comments section are 5o characters.
View Publish
● SQL Server = unlimited
● UDB = unlimited
Note that the publish views cast down to a varchar: SQL = 8000, UDB = 1500 (that is you only
see 8000 characters in the SQL view)
● Oracle = 4000 characters
Table-only Publish
Table-only publish varies by format
Text fields (epReportingText)
● SQL Server = 8000
● UDB = unlimited
● Oracle = 4000
Limits for Numerical Cells
The following limits are for Analyst and Contributor numerical cells.
Administration Guide 395

Appendix H: Data Entry Input Limits
396 Contributor
Numerical Cells in Analyst
There are no limits to the number of characters in numeric cells that you can enter in Analyst,
however, when the numbers get too large to fit, they will display in a scientific format, for example
2345628363E205.
Numerical Cells in Contributor
You can enter up to 60 characters in a numerical formatted cell in the Contributor Web client.

Glossary
access tables
In Contributor, controls access to cells in cubes, whole cubes, and assumption cubes.
accumulation D-links
D-links that consolidate data from a source D-cube to a D-cube based on text data.
administration job
An administration task that runs on job servers and is monitored by the Contributor Administration
Console. These tasks are commonly referred to as jobs. Some examples of jobs are reconcile, publish,
cut-down models, links.
administration link
A link that enables an administrator to move data between Contributor applications. An adminis-
tration link can contain multiple applications and cubes as the sources and targets of the link. A
link can contain multiple elements which target either the development or the production application.
Administration links run using the job architecture and so are scalable.
administration machine
In IBM Cognos Planning, the computer that is used to operate the Contributor Administration
Console.
administration server
In IBM Cognos Planning, the server that contains the planning components package (COM+
package) and where control of the online application is maintained. You connect to this machine
when you first run the Contributor Administration Console.
application
In IBM Cognos Planning, a Contributor application. Contributor applications are used for the
collection and review of data from hundreds, or thousands of Web servers. One application can be
used by many users in different locations at the same time.
Application server
See Job Server.
assumption cube
In IBM Cognos Planning, a cube that contains data that is moved into the Contributor application
when the application is created or synchronized. It does not contain the e.List. Therefore, data
applies to all e.List items, and is not writable. The data it contains is often named "assumption
data."
Administration Guide 397

Glossary
398 Contributor
A-table
In Analyst, an allocation table that shows how two lists correspond. It is useful for transferring
data when no character matches are possible between lists of items.
BiF
Built in Function. In IBM Cognos Planning a BiF is a special calculation formula that was set up
specifically for planning. For example, depreciation, discounted cashflow, forecasting using different
drivers, and stock purchase prediction based on future sales.
bounce
In IBM Cognos Planning, a term used to refer to the removal of the currently editing owner of an
e.List item in the Contributor Web client. A planner or reviewer may "bounce" the owner.
commentary
In IBM Cognos Planning, commentary represents any additional information attached to Contributor
cells, tabs, or e.List items, including both user annotations and attached files. You can use adminis-
tration links, system links and local links to copy commentary.
contribution
In IBM Cognos Planning, data that is entered into an e.List in the Contributor application.
Contributor Administration Console
A tool which enables administrators to publish an Analyst business model to the Web, manage
access settings and model distribution, and configure the user's view of the model.
cube
A physical data source containing a multidimensional representation of data. A cube contains
information organized into dimensions and optimized to provide faster retrieval and navigation in
reports. In IBM Cognos Planning, a cube (see also D-Cube) corresponds to a tab on Contributor
client user interface.
current owner
In Contributor, the person who is editing or lasted opened an e.List item for edit.
cut-down models
In IBM Cognos Planning, customized copies of the master model definition that have been cut down
to include only the specific elements required for a particular e.List item.
datastore
In IBM Cognos Planning, the location where one or more Contributor applications are stored. A
datastore contains the information needed to connect to a database supporting the Contributor
applications.

D-cube
In IBM Cognos Planning, a multi-page speadsheet made up of two or more dimensions. A D-cube
must contain at least two dimensions. In Contributor a D-cube is referred to as a cube.
dimension
In IBM Cognos Planning, the rows, columns, and pages of a cube are created from dimensions.
Dimensions are lists of related items such as Profit and Loss items, months, products, customers,
and cost centers. Dimensions also contain all the calculations. One dimension can be used by many
cubes.
In IBM Cognos 8 BI, a dimension is a broad grouping of descriptive data about a major aspect of
a business, such as products, dates, or locations. Each dimension includes different levels of members
in one or more hierarchies and an optional set of calculated members or special categories.
D-link
In Analyst, a link that copies information in and out of cubes, and sometimes to and from text or
ASCII files.
D-list
An alternative term for dimension.
D-list format
Lets you enter text from another D-List in a row or a column. The format may be used in database-
type functions to consolidate data in a similar manner to query-style reports.
drill down
In IBM Cognos Planning, drill down is a technique used to analyze D-Cube data that was imported
by a D-Link. You can drill down on any single cell in a D-Cube. If the cell contains data transferred
by a D-Link, drill down opens a view of the source data. If the data was imported from another D-
Cube, drill down opens the appropriate selection from the source D-Cube. If the data was imported
from an external source (a mapped ASCII file or an ODBC database), drill down extracts the relevant
data from the source file and displays it in a special drill-down results dialog box.
In IBM Cognos 8 BI, drill down refers to the act of navigating from one level of data to a more
detailed level. The levels are set by the structure of the data. See also drill up.
e.List
The basis for the structure of a Contributor application. An e.List is a hierarchical dimension which
typically reflects the structure of the organization (for example, cost centers and profit centers).
editor
In IBM Cognos Planning, a planner or reviewer who is editing a contribution
extensions
Glossary
In IBM Cognos Planning, extends the functionality of the Contributor Administration Console and
Classic Web Client. There are two types of extensions: Admin Extensions and Client Extensions.
Administration Guide 399

Glossary
400 Contributor
Admin Extensions run in the Administration Console. Client Extensions are activated from the tool
options on the Classic Contributor Grid.
file map
In Analyst, a file map tells the program how to split an ASCII or text file into columns of data. A
file map puts in the divisions, or breaks, between one column of numbers and another. It defines
the start point and width of each column of data within an ASCII file, and denotes whether the
column is a numeric, text, or date field. If there is only one column, a file map is superfluous. File
maps are always necessary when using an ASCII file as the source for a D-Link.
Get Data
In IBM Cognos Planning, a command in the Web client that loads the screen that displays local
links and system links.
go to production
In IBM Cognos Planning, a process in the Contributor Administration Console that takes the
development application and creates the live production application.
grid
In IBM Cognos Planning, a tabular form for viewing and entering data.
GUID
Global Unique Identifier. A unique internal reference for items in a model. For example, when you
add a dimension item, this item is assigned a GUID.
hold
In IBM Cognos Planning, a function that protects a cell against breakback.
import block
In IBM Cognos Planning, a package of data from Analyst or an external system that is validated
and prepared for import into a Contributor application. The import block is imported into the
Contributor application datastore via a reconcile job.
import link
A function used in Analyst to update the items in a dimension on a regular basis from a source file
or database.
job server
In IBM Cognos Planning, a machine that runs the administration jobs. There may be multiple job
servers. A job server is sometimes referred to as an application server.
library
In IBM Cognos Planning, the storage location of the model. The library includes a group of connected
Analyst objects: macros, reports, D-Links, selections, D-Cubes, maps, A-Tables, D-Lists, and formats.
A library is similar to a Windows directory.

local links
In IBM Cognos Planning, a link defined and run by a user in the Web client.
lock
In IBM Cognos Planning, a function that prevents data being entered into cells whether by typing
or via a D-Link.
lookup d-links
In IBM Cognos Planning, D-Links that look up data from a source D-Cube based on text data. It
uses a database D-Cube as a target.
macros
In IBM Cognos Planning, a single object defined by an administrator to automate a series of
Administration tasks in Contributor. Each task is known as a step. In Analyst, a set of commands
that have been recorded and grouped together as a single command, which is used to automatically
complete a list of instructions in one step.
match descriptions
In IBM Cognos Planning, used to automatically match source and target dimension items with the
same name. In addition, match descriptions can be used to perform an allocation by date.
maximum workspace
(MAXWS) The amount of memory reserved for Analyst. May be changed to allow larger models
to run more effectively.
model
A physical or business representation of the structure of the data from one or more data sources.
A model describes data objects, structure, and grouping, as well as relationships and security.
In IBM Cognos 8 BI, a design model is created and maintained in Framework Manager. The design
model or a subset of the design model must be published to the IBM Cognos 8 server as a package
for users to create and run reports.
In IBM Cognos Planning, a model is a group of D-Cubes, D-Lists, D-Links, and other objects stored
in a library. A model may reside in one or more libraries, with a maximum of two for Contributor.
namespace
For authentication and access control, a configured instance of an authentication provider. Allows
access to user and group information.
In XML, a collection of names, identified by a URI reference, which are used in XML documents
as element types and attribute names.
In Framework Manager, namespaces uniquely identify query items, query subjects, and so on. You
import different databases into separate namespaces to avoid duplicate names.
Glossary
Administration Guide 401

Glossary
402 Contributor
offline grid
In IBM Cognos Planning, the application that is used to access a section of an offline Contributor
application. The purpose is to enable users to enter or view data while there is no network connec-
tion.
owner
In Contributor, a user who is assigned to an e.List item through the Rights screen and is permitted
to edit or review it. These rights may be directly assigned, or may be inherited.
planner
In IBM Cognos Planning, a person who enters data in the Contributor application in the Web client.
product application
In IBM Cognos Planning, the version of the Contributor application seen by the Web-client user.
The version of the Contributor application that is seen in the Contributor Administration Console
is the development application.
protect
In IBM Cognos Planning, a function that is used to prevent data from being typed into a cell.
However, data can still be transferred into a protected cell via a D-Link.
publish
In IBM Cognos 8 BI, refers to exposing all or part of a Framework Manager model or Transformer
PowerCube, via a package, to the IBM Cognos 8 server, so that it can be used to create reports and
other content.
In IBM Cognos Planning, refers to a function that is used to copy the data from Contributor or
Analyst to a datastore, typically so it can be used for reporting purposes.
publish container
In IBM Cognos Planning, a datastore container created specifically to publish data to.
reconciliation
In IBM Cognos Planning, a process that ensures that the copy of the Contributor application that
the user accesses on the Web is up to date, for example, all data is imported. Reconciliation takes
place after Go to Production has run and a new production application is created.
reviewer
In IBM Cognos Planning, a person who reviews the submissions of reviewers or planners.
rights
In Contributor, assigning rights enables administrators to determine what users can do in a Con-
tributor application. Rights determine whether a user can view, edit, review, and submit data.

saved selections
In Contributor, dynamic groups of items from a dimension or e.List. When used in conjunction
with access tables, access tables provide a high level of control over the access or cells.
In Extensions, sets of data configured during an export or refresh. A user can choose a saved
selection and update just the data without reconfiguring the report or export criteria.
In Analyst, sets of data used to save a specific D-Cube orientation, including a selection of rows,
columns, and pages for later use. The selected items, sort order, and slice of the D-Cube are all
saved in a named selection.
synchronize
In Contributor, a function used to update all cubes, links, and so on in an application when the
underlying objects in Analyst change. Changes include renaming dimensions, adding, deleting, or
renaming dimension items.
system links
In Contributor, a link that is defined by the Contributor administrator and run by a user in the
Web client. This is part of the Get Data functionality in the Web client.
table-only layout
In IBM Cognos Planning, a publish schema that consists of a table-only layout, and is particularly
suitable for the Generate Framework Manager Model extension.
view layout
Glossary
In IBM Cognos Planning, a publish schema that consists of a layout of views over text values.
Administration Guide 403

Glossary
404 Contributor

Index
Symbols
.cpf, 303
A
access
Contributor, 88
access control, 29
access levels, 123
definition, 121
hidden, 121
loss of access to e.List items, 255
no data, 121
no data settings and block sizes, 123
planner data entries, 137
reading, 121
updating no data settings, 122
writing, 121
access permissions
users, 32
access rights
go to production options, 82
granting, 39
access tables, 22, 23, 119
changing, 126, 136
cut-down models, 130, 140
default, 393
definition, 397
editing, 125
exporting, 129
formatting, 127
importing, 126
importing data, 137
large, 129
memory usage, 130
performance issues, 129
rules, 120
viewing imported, 128
accumulation D-links
definition, 397
act a system link source, 79
adding
applications, 60
e.List items, 102
Admin extensions, 301, 329
Generate Framework Manager Model, 306
running, 301
Administration Console
actions that run jobs, 51
performance issues, 129
administration jobs
definition, 397
administration links, 147
allocation table, 155
Contributor, 22
CPU usage, 159
creating, 149
definition, 397
exporting, 157
importing, 157
macros, 23
model changes, 160
moving commentary, 149
rights, 39
running, 157
setting source batch size, 160
setting target batch size, 161
synchronize, 156
troubleshooting memory issues with detailed fact
query subject, 169
troubleshooting tuning settings, 161, 162
tuning, 158
upgrading, 329
using existing, 161
validate, 156
administration machines
definition, 397
administration servers
definition, 397
administrators, 25
multiple, 22
admin options, 79
Administration Guide 405

Index
allocation table in Administration Link, 155
allow automatic cab downloads and installations, 71
allow bouncing, 74
allow bouncing example, 77
allow multi-e.List item views, 72
allow reviewer edit, 74
allow slice and dice, 72
Analyst
Generate Framework Manager Model wizard, 306
Analyst - Contributor links, 347
upgrading, 329
annotations
deleting, 289
display audit annotations in Web client, 74
annotations import threshold, 74
annotations paste threshold, 74
anonymous access, 35
application containers
rights, 39
application details
viewing, 79
application folders, 68
monitoring, 59
application options, 74
applications
adding, 60
creating, 24, 60, 65
definition, 397
information, 70
linking, 89
monitored, 58
synchronizing, 179
upgrading, 60
application tabs
translating, 187
application XML, 79
Application XML
issues, 380
assign access rights, 39
assigning rights, 24
assumption cube
definition, 397
assumption cubes, 119, 123, 126
A-table
definition, 397
attach documents, 290
406 Contributor
attached documents, 290
configuration, 71
configuring the properties, 290
maximum number, 290
publishing, 291
audit annotations, 289
recording, 74
authentication, 29
authentication providers, 29, 35
automation, 23
B
backups, 357
base language, 79
base models, 306
best practices, 13
BiFs
definition, 398
supported in Contributor, 343
binary large objects, See large objects (LOBs, BLOBs,
CLOBs)
BLOBs, See large objects (LOBs, BLOBs, CLOBs)
block sizes and no data access settings, 123
BMTReport.log, 361
bounce
definition, 398
bouncing
allowing, 74
example, 77
breakback
setting, 72
business cases, 315
business logic
defining, 231
business rules
defining, 237
enforcing, 231
planning for, 232
Business Viewpoint Client
C
managing Contributor master dimensions, 314
cab downloads
caching
allowing, 71
Contributor data for IBM Cognos 8, 306

Calculation Engine (JCE)
error logs, 382
capabilities, 34
capacity planning, 359
cascaded models, 146
cascade rights, 38
changing
applications and translations, 185
e.List, 136
character large objects, See large objects (LOBs, BLOBs,
CLOBs)
client-executed links, 144
client extensions, 300
configuring, 301
extension groups, 300
client-side cache, 74
client-side reconciliation, 54
CLOBs, See large objects (LOBs, BLOBs, CLOBs)
CM-REQ-4159, 362
code pages, 191
Cognos 8, See IBM Cognos 8
Cognos namespace, 29
color
selecting for changed values, 72
column headings
EListItemCaption, 100
ELIstItemIsPublished, 101
EListItemName, 100
EListItemOrder, 100
EListItemParentName, 100
EListItemReviewDepth, 101
EListItemViewDepth, 100
commentaries
deleting, 289
commentary
breakback considerations, 291
copy, 291
cumulative, 291
definition, 398
deleting, 290
moving with administration links, 149
moving with system links, 149
components tabs
translation, 187
concurrency, 359
condition
specifying for event, 226
configure application, 70
configuring attached document properties, 290
configuring the Web client rights, 39
contribution e.List items, 109
contributions, 26, 87
definition, 398
Contributor add-ins
Microsoft Excel, 91
Contributor Administration Console
definition, 398
contributor-only cubes, 78
copy
import, 175
copy commentary, 291
copy development e.List item publish setting to produc-
tion application, 82
copying
Analyst Contributor links, 350
copyright material
creating
printing, 15
application, 65
applications, 39, 60
applications using a script, 39
connections from IBM Cognos 8 BI products, 306
cube help, 375
datasource connections, 303
detailed fact query subject, 167
Framework Manager projects, 165, 303
planning packages, 244
Planning tables, 47
PowerCubes, 309
production applications, 25
publish containers, 39
scripts, 39
source files, 173
system links, 163
Web sites, 25
credentials, 44
cube dimension order
setting, 72
cube instructions, 78
cube order
setting, 71
Index
Administration Guide 407

Index
cubes, 21, 119
access tables, 124
changing, 250
creating help, 375
definition, 398
detailed help, 375
importing data, 173
no access tables, 126
types, 119
cumulative commentary, 291
current owners, 95
definition, 398
cut-down models, 74, 138
access tables, 140
cutting down a D-List to no data does not affect
dimension size, 140
definition, 398
examples, 142
Go to Production process, 256
impact from access tables, 130
languages, 246
limitations, 138
options, 139
processes, 138
restrictions to cutting down dimensions, 140
translations, 139
cut down to no data does not affect dimension size, 140
D
data
loss from changes, 179
moving using links, 145
database object names, 266
databases
backing up, 357
object names, 280
privileges, 356
data blocks, 245
dataCacheExpirationThreshold parameter, 306
data dimensions for publish, 263
data entry
validating, 231
data entry limits, 395
numerical cells, 395
data loads, 360
408 Contributor
data source connections, 303
creating, 306
data sources
TM1, 147
datastores
definition, 398
rights, 39
datastore servers, 48
information, 49
data validation, 231
and e.List items, 240
defining business rules, 237
defining fail actions, 239
impact of aggregations, 233
setting up, 232
setting up D-Cubes in Analyst, 233
DB2 import utility, 359
D-Cubes
definition, 398
setting up pre- and post-aggregation ordering, 233
DDL scripts, 356
delete
job server cluster, 56
delete annotations
rights, 39
Delete Commentary, 394
deleting
annotations, 289
annotations for e.List items, 289
commentaries, 289
commentary, 290
Contributor applications, 60
e.List items, 104
import queues, 176
jobs, 55
namespaces, 31
server definitions, 60
undefined items, 98
deployment
macro, 210
deployment status, 172
designing e.Lists, 24
detailed fact query subject, 167
memory usage, 169
developing plans, 24

development applications, 247
rights, 39
development environment, 170
dimensions
changing, 252
definition, 399
D-Links, 341
editing selections, 116
saving selections, 115
dimensions for publish
selecting, 82
dimensions for publishing
rules for non-defined, 303
disable job processing, 56
display audit annotations in Web client, 74
display warning message on zero data, 79
D-Links, 22
definition, 399
designing Contributor model in Analyst, 339
dimensions, 341
D-List aggregations
impact on data validation, 233
D-List format
D-Lists
definition, 399
definition, 399
importing using IQDs, 312
drill down
definition, 399
dynamic objects, 357
E
e.List item properties
previewing, 293
e.List items
adding, 102
configuring display number, 96
deleting, 104
multiple owners, 95
reconciliation, 256
reordering, 103
e.Lists, 21, 93, 98, 106
aggregation and data validation, 233
associating validation rules, 240
changes, 136
default options, 393
definition, 399
designing, 24
importing file examples, 99
importing from Performance Applications, 312
reconciliation, 104
editor lagging, 255
editors
definition, 399
EListItemCaption column heading, 100
ELIstItemIsPublished column heading, 101
EListItemName column heading, 100
EListItemOrder column heading, 100
EListItemParentName column heading, 100
EListItemReviewDepth column heading, 101
EListItemViewDepth column heading, 100
email
sending on save, 74
sending on submit, 74
e-mail, 63
links, 378
email character separator, 71
E-mail function, 27
environments, 170
error messages
errors
importing the e.List and rights, 97
out of memory when exporting during deploy-
ment, 173
handling, 379
logging, 383
estimating model and data block size, 141
eTrust SiteMinder namespace, 29
event
condition, 226
event condition
specifying, 226
Everyone group, 37
examples
e.List files, 99
importing data source files, 174
rights file, 111
Export for Excel extension, 312
exporting
access tables, 129
Analyst library, 170
application links, 170
Index
Administration Guide 409

Index
e.Lists, 101
macros, 170
model, 170
rights, 101
export tables, 270
expression
specifying for event condition, 226
extending functionality, 21
extensions
definition, 399
group, 300
external namespaces
F
eTrust SiteMinder, 29
IBM Cognos Series 7, 29
LDAP, 29
Microsoft Active Directory, 29
NTLM, 29
SAP, 29
failure of reconciliation, 54
file formats, 99
file maps
definition, 400
filesys.ini, 47
file types
IQDs, 312
fill and substitute mode, 353
Filters
importing from SAP BW, 167
financial planning, 300
finding, 98
e.Lists, 98
information, 14
rights, 98
finish screen, 256
folders, 68
fonts, 192
force to zero option, 137
formatting imported access tables, 127
Framework Manager, 302
creating and publishing a Framework Manager
package, 166
creating a project and import metadata, 165
creating projects, 303
model troubleshooting, 361
410 Contributor
G
model updating, 309
Generate Framework Manager Model extension
accessing published data from IBM Cognos 8, 306
generate scripts, 79
generating
Transformer models, 309
Get Data
definition, 400
global administration
rights, 39
go to production
definition, 400
go to production options, 82
access rights, 82
planning package setting, 82
Go to Production process, 243
buttons, 27
e.List items to be reconciled, 256
finishing, 256
importing data details, 254
importing process, 177
invalid owners and editors, 254
model changes, 250
options, 248
rights, 39
running, 248
show changes screen, 249
grid options, 72
grids
default, 389
definition, 400
group extensions, 300
groups, 31
GUID
H
help, 27
validate, 113
definition, 400
adding, 78
getting, 14
translating, 191
hidden items, 120
history tracking, 74

hold
definition, 400
HTML formatting, 375
hypertext links, 377
I
IBM Cognos 8, 302
caching Contributor unpublished data, 306
IBM Cognos 8 Business Intelligence studios
connecting to data sources, 306
IBM Cognos Performance Applications, 312
IBM Cognos Resource Center, 14
IBM Cognos Series 7 namespace, 29, 335
illegal characters, 387
images, 375
import blocks
definition, 400
import block size, 79
Import data details tab, 254
import files
prepared data blocks, 176
preparing, 177
testing, 177
Import from IQD wizard
Performance Applications, 312
importing
access tables, 126
Analyst library, 170
application links, 170
copy process, 175
data, 39, 143
data into cubes, 173
e.Lists, 39, 96, 101
example, 174
loading, 175
macros, 23, 170
models, 170
multiple times, 149
preparing, 176
rights, 96
rights file formats, 110
SAP BW data, 167
translated files, 190
import links
definition, 400
import location, 79
import options, 79
import queues, 176
incremental, 279
incremental publish, 279
information
finding, 14
inherited rights, 108
integration, 299, 302
IBM Cognos Contributor and IBM Cognos Control-
ler, 312
Invalid owners and editors tab, 254
IQD files
importing D-Lists and e.Lists, 312
items tables for table-only layout, 267
J
jobs
architecture, 358
canceling, 54
deleting, 55
managing, 49, 52
pausing, 54
preparing import jobs, 359
publishing, 53, 359, 360
running, 25
run order, 50
securing, 51
securing scheduled, 44
types, 49
job server clusters
adding, 56
rights, 39
job servers, 56
L
lagging
adding, 56
adding objects, 58
definition, 400
rights, 39
editor, 255
large access tables, 129
large objects (LOBs, BLOBs, CLOBs), 358
LDAP namespace, 29
libraries
Analyst guidelines, 337
Index
Administration Guide 411

Index
definition, 400
limitations, 363
limitations when importing IBM Cognos packages, 363
limit document size, 71
limits for data entries, 395
link access
linking
rights, 39
to existing applications, 39
linking to applications, 89
linking to a publish container
rights, 39
link modes, 149
links
administration, 147, 149, 157
Analyst - Contributor, 347
changing, 252
client run, 144
local, 145
memory usage, 351
model designs, 146
order, 148
system, 144, 163
using to move data, 145
loading data, 175, 360
LOBs, See large objects (LOBs, BLOBs, CLOBs)
local links, 145
lock
definition, 400
definition, 401
lock escalation, 358
LOCKLIST setting, 357
LogFetcher utility, 385
lookup d-links
M
macro
definition, 401
deployment, 210
macros, 23
administrator links, 219
authentication, 43
automating tasks, 193
creating, 194
definition, 401
deleting commentary, 217
412 Contributor
development, 202
executing a command line, 222
executing an Admin extension, 218
IBM Cognos Connection, 43
importing access tables, 23, 206
importing e.List and rights, 23
importing e.Lists and rights, 208
managing job servers, 199
production, 211
publishing, 23, 211
rights, 42
rights needed to transfer, 42
running, 224
securing scheduled, 44
synchronizing, 23
troubleshooting, 229
upgrading, 329
upload development model, 210
maintaining the application
rights, 39
manage extensions
rights, 39
managing
jobs, 49, 52
sessions, 61
managing Contributor master dimensions
Business Viewpoint Client, 314
match descriptions
definition, 401
matrix management, 147
maximum number of attached documents, 290
maximum workspace
definition, 401
MAXLOCKS setting, 357
measures dimension, 303
metadata, 357
organizing data using Framework Manager, 303
Microsoft Active Directory, 29
Microsoft Excel
design considerations, 311
migrating applications, 170
model
designing Analyst model for Contributor, 337
model and data block sizes, 141
model changes screen, 250

model designs
models
using links, 146
advanced changes, 182
changes that impact publish tables, 262
creating in Framework Manager, 303
definition, 245, 401
details, 68
using Generate Framework Manager Model func-
tionality, 306
modify datastore connection details
rights, 39
modifying rights manually, 111
monitored applications, 58
Monitoring Console, 61, 172
moving data using links, 145
multi-administration roles, 22
multi e.List item views, 72
multiple access tables, 135
multiple administrators, 22
multiple owners
N
e.List items, 95
namespace
validate users, 113
namespaces, 29
definition, 401
deleting, 31
multiple, 29
restoring, 31
upgrade, 335
See Also authentication providers
naming conventions, 357
navigation, 71
No Data access level, 120
NTLM namespace, 29
numerical cells
O
limits, 395
objects, 357
offline
store, 90
offline grids
definition, 401
offline working
preventing, 74
Oracle, 48
orientation, 72
out of memory error when exporting during deploy-
ment, 173
owners, 95
definition, 402
ownership
P
e.List items, 112
parameters
dataCacheExpirationThreshold, 306
LOCKLIST, 357
MAXLOCKS, 357
percentages, 312
performance
CPU usage, 159
model changes, 160
tuning settings, 161, 162
variables, 159
permissions, 105, 356
planner, 26
rights, 109
planner-only cubes, 78
planners
definition, 402
Planning Administration Domain
upgrading, 329
Planning Contributor Users, 33
Planning Data Service, 302
planning package, 244, 248
Framework Manager, 302
Go to Production, 302
Planning Rights Administrator, 33
Planning tables
plans
creating, 47
developing, 24
post production tasks, 256
precalculated summaries, 261
prepared data blocks, 176
preparing data, 176
preproduction process, 256
prevent client-side reconciliation, 82
Index
Administration Guide 413

Index
preventing
client-side reconciliation, 55
prevent offline working, 74
preview data
rights, 39
previewing
e.List item properties, 293
e.List items, 104
production workflow, 293
properties, 293
previewing the production workflow, 293
printing copyright material, 15
Print to Excel extension, 312
privileges, 356
product application
definition, 402
production
tasks, 246
production applications, 245
rights, 39
production environment, 170
production workflow
projects
previewing, 293
creating in Framework Manager, 303
prompt to send email on reject, 74
prompt to send email on save, 74
prompt to send email on submit, 74
prompt to send email when user takes ownership, 74
properties
protect
previewing, 293
definition, 402
providers
security, 29
publish, 259, 279
access rights, 260
data dimensions, 263
data types, 271
export tables, 270
hierarchy tables, 267
items tables, 267
layouts, 259
scripts, 260
select e.List items, 261
table-only layout, 265
414 Contributor
publish containers
definition, 402
rights, 39
publish data
rights, 39
publishing
definition, 402
macros, 23
publishing attached documents, 291
publish options, 79
R
read access, 120
recalculate after every cell change, 72
reconciliation, 54
changes to access tables, 136
definition, 402
e.Lists, 104
prevent client-side, 82
record audit annotations, 74
reject depth, 105
related documentation, 13
removing applications, 60
rights, 39
reordering
e.List items, 103
reporting directly from publish tables, 261
reporting on live data, 302
resetting development to production, 27
restoring
namespaces, 31
review depth, 105
review e.List items, 108
reviewer edit
allowing, 74
reviewers, 26
access levels, 137
definition, 402
rights, 108
reviews, 87
rights, 107
assigning, 24
default, 393
definition, 402
e.List items, 105
file formats, 110

inherited, 108
modifying, 111, 112
reordering, 112
submitting, 108
summary, 107, 113
user, 107
roles, 31
valdiate, 113
row-level locking, 358
rule sets
associating to e.Lists, 240
defining fail actions, 239
running jobs, 25
run order of jobs, 50
S
sample HTML text, 375
SAP BW
importing data, 167
limitations, 363
SAP namespace, 29
saved selections, 22, 115
definition, 402
editing, 116
Save function, 27
saving application XML for support, 79
scenario dimensions, 261
scheduler credentials, 44
jobs, 51
script.sql, 69
scripts creation path, 79
searching
e.Lists, 98
rights, 98
translating, 191
securing jobs, 51
security, 356
access control, 29
authentication, 29
providers, 29
upgrade, 335
validate users, 113
Web client settings, 89
security overview, 34
select color for changed values, 72
send email on reject
prompt, 74
server call timeout, 380
servers for datastores, 48
server-side reconciliation, 54
sessions
managing, 61
set an application on or offline
rights, 39
Set Offline function, 27
Set Online function, 27
setting data cache expiration, 306
simplifying models, 312
size of models, 68
size of models and data blocks, 141
slice and dice
allowing, 72
source files
creating, 173
SQL, 357
SQL Server, 48
static objects, 357
stop job processing, 56
submitting rights, 108
synchronize
definition, 403
synchronize administration link, 156
synchronizing
advanced model changes, 182
avoiding data loss, 180
data loss, 179
examples, 181
Generate Scripts option, 180
macros, 23
rights, 39
system administrator, 29
system link, 79
system links, 144
creating, 163
definition, 403
using to move commentary, 149
system locale, 191
system settings, 44
T
table-level locking, 358
Index
Administration Guide 415

Index
table-only layouts
definition, 403
table-only publish layout, 265
table-only publish post GTP, 79
take ownership
send email, 74
test environment, 170
text formatted cells
data entry limits, 395
timeout, 380
TM1
data sources, 147
translating
help, 191
searches, 191
strings, 187
translation
application tabs, 187
assigning to users, 185
changes, 185
cycles, 185
exporting files, 190
importing and exporting files, 189
importing files, 190
rights, 39
trees, 87
troubleshooting
U
Generate Framework Manager Model exten-
sion, 361
importing from IBM Cognos package, 366
importing IBM Cognos packages, 363
macros, 229
modeled data import, 366
unable to change model design language, 362
unable to connect to Oracle database, 361
unable to create framework manager model, 361
unable to retrieve session namespace, 362
underlying values, 312
unowned items, 95
unpublished Contributor data, 306
unregistering
namespaces, 31
upgrading
Admin extensions, 329
416 Contributor
administration links and macros, 329
Analyst - Contributor links, 329
applications, 60, 329
Contributor web site, 336
planning administration domain, 329
rights, 39
Web sites, 336
what is not upgraded in Contributor, 329
wizards, 332
use client-side cache, 74
user annotations, 289
user models, 306
users, 21, 31, 101
V
validate
classes and permissions, 32
loss of access to e.List items, 255
validate, 113
users, 113
validate administration link, 156
validation methods, 231
version dimensions, 261
view application details, 79
view depth, 101, 106
viewing
imported access tables, 128
view layout
definition, 403
view rights, 113
W
warning messages
importing the e.List and rights, 97
Web clients
settings, 89
web client settings, 71
web client status refresh rate, 74
Web sites, 87
wizards
creating, 25
upgrading, 336
Import from IQD wizard, 312
workflow state definition, 295
write access, 120

X
XML
default locations and filenames, 390
Index
Administration Guide 417