Ug CXR

Planning Analytics for Microsoft Excel
Version 2.0.0
Version 2 Release 3
User Guide
IBM
Note
Before you use this information and the product it supports, read the information in “Notices” on page 209.
Product Information
This document applies to IBM Planning Analytics Version 2.0 and might also apply to subsequent releases.
Licensed Materials - Property of IBM
Last updated: 2017-09-14
© Copyright International Business Machines Corporation 2009, 2017.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Introduction......................................................................................................................... ix
Chapter 1. What's new in IBM Planning Analytics for Microsoft Excel...................................... 1

2.0.25 - Feature updates, September 12, 2017............................................................................................................... 1
2.0.23 - Feature updates, July 21, 2017...........................................................................................................................1
2.0.22 - Feature updates, June 23, 2017......................................................................................................................... 1
2.0.21 - Feature updates, June 2, 2017........................................................................................................................... 1
2.0.20 - Feature updates, May 13, 2017...........................................................................................................................1
2.0.18 - Feature updates, April 8, 2017............................................................................................................................1
2.0.0 - Feature updates, December 16, 2016.................................................................................................................. 1
Chapter 2. Get started........................................................................................................... 5

Get oriented........................................................................................................................................................................5
Before you begin................................................................................................................................................................ 7
Start IBM Planning Analytics for Microsoft Excel..............................................................................................................7
The IBM Planning Analytics tab.........................................................................................................................................8
Report types....................................................................................................................................................................... 8
Planning Analytics for Microsoft Excel report types.................................................................................................... 9
Connect to TM1 ............................................................................................................................................................... 11
Notes for IBM TM1 Perspectives users........................................................................................................................... 11
Enable trust access to the VBA project object model............................................................................................... 13
Open an IBM TM1 Perspectives workbook................................................................................................................13
Upgrade IBM TM1 Perspectives action buttons........................................................................................................ 14
Chapter 3. Work with data and reports................................................................................. 15

Set up a connection......................................................................................................................................................... 15
Log on to a connection..................................................................................................................................................... 16
Open a data source ......................................................................................................................................................... 16
Refresh a data source or package................................................................................................................................... 17
Change the system and data source............................................................................................................................... 17
Open and download workbooks...................................................................................................................................... 17
Open a workbook from the TM1 Server Application Folder...................................................................................... 17
Find items in the source tree........................................................................................................................................... 18
Search for members in an IBM Planning Analytics data source............................................................................... 18
Refresh data..................................................................................................................................................................... 19
Clear cell content............................................................................................................................................................. 19
Convert dynamic data to snapshots (static data)........................................................................................................... 20
Copy and move worksheets.............................................................................................................................................21
Share your analysis.......................................................................................................................................................... 21
Publish a workbook to a TM1 Server Application Folder.......................................................................................... 21
Run Cognos TM1 TurboIntegrator processes................................................................................................................. 22
Chapter 4. Set options......................................................................................................... 23

IBM settings..................................................................................................................................................................... 23
Start application......................................................................................................................................................... 23
Update Connection URLs........................................................................................................................................... 23
Set up forms-based user authentication................................................................................................................... 24
Logging........................................................................................................................................................................24
Cache management....................................................................................................................................................24
Utilities........................................................................................................................................................................25
IBM Planning Analytics settings...................................................................................................................................... 25
iii
Application settings....................................................................................................................................................25
Exploration or list settings......................................................................................................................................... 30
Custom report settings...............................................................................................................................................35
Quick report settings.................................................................................................................................................. 36
Action button settings................................................................................................................................................ 37
Chapter 5. Explore TM1 data................................................................................................ 39

Exploration Views and lists..............................................................................................................................................39
Create a list.................................................................................................................................................................39
Create an Exploration View........................................................................................................................................ 40
Set properties............................................................................................................................................................. 50
Insert Microsoft Excel calculations............................................................................................................................51
Change the system and data source used by an exploration....................................................................................51
Quick Reports...................................................................................................................................................................51
Create a Quick Report................................................................................................................................................ 51
Add members............................................................................................................................................................. 53
Replace members.......................................................................................................................................................54
Refresh........................................................................................................................................................................54
Publish........................................................................................................................................................................ 55
Delete..........................................................................................................................................................................55
Edit.............................................................................................................................................................................. 55
Quick Report double-click options............................................................................................................................ 56
Change the system and data source used by a Quick Report................................................................................... 56
Dynamic Reports..............................................................................................................................................................57
Create a Dynamic Report........................................................................................................................................... 57
Refresh, rebuild, or recreate...................................................................................................................................... 57
Expand and collapse rows..........................................................................................................................................58
Suppress or display zeros.......................................................................................................................................... 58
Edit the row set...........................................................................................................................................................58
Change context members.......................................................................................................................................... 59
Insert columns........................................................................................................................................................... 59
Insert rows..................................................................................................................................................................59
Display the data source or package of a formula...................................................................................................... 59
Change the server and data source used by a Dynamic Report................................................................................59
Report format............................................................................................................................................................. 60
Publish........................................................................................................................................................................ 62
Usage notes................................................................................................................................................................ 62
Create a Custom Report...................................................................................................................................................63
Convert a TM1 Exploration View to a Custom Report............................................................................................... 63
Create Custom Reports by using a view.................................................................................................................... 63
Create Custom Report manually................................................................................................................................ 64
Sets for TM1..................................................................................................................................................................... 64
Create sets..................................................................................................................................................................65
Search for members in a set...................................................................................................................................... 65
Paste members into the set editor.............................................................................................................................66
Change members in a view by using advanced features.......................................................................................... 67
Convert a dynamic set to static..................................................................................................................................68
Modify TM1 data.............................................................................................................................................................. 68
Writeback mode......................................................................................................................................................... 68
Toolbar options...........................................................................................................................................................70
Sandboxes.................................................................................................................................................................. 70
Edit TM1 data in reports.............................................................................................................................................72
IBM TM1 functions...........................................................................................................................................................80
TM1 worksheet functions in IBM Planning Analytics for Microsoft Excel.................................................................80
Display the data source or package of a formula.................................................................................................... 105
Change the server and data source of TM1 formulas............................................................................................. 105
DBR and DBRW formulas......................................................................................................................................... 105
SUBNM formulas...................................................................................................................................................... 107
iv
Chapter 6. Cube viewer...................................................................................................... 109
Data entry.......................................................................................................................................................................109
Data display................................................................................................................................................................... 110
Sort rows and columns.................................................................................................................................................. 111
Show and hide totals..................................................................................................................................................... 111
Suppress zeros...............................................................................................................................................................112
Expand levels................................................................................................................................................................. 112
Display cell values as percentages................................................................................................................................112
Drill up or down on members........................................................................................................................................ 112
Hide rows and columns................................................................................................................................................. 113
Add a calculation to a view............................................................................................................................................113
Sandboxes......................................................................................................................................................................114
Copy and paste.............................................................................................................................................................. 114
Data spreading...............................................................................................................................................................115
Create a report............................................................................................................................................................... 115
Multiple hierarchies....................................................................................................................................................... 116
Quick data entry commands......................................................................................................................................... 116
Chapter 7. Action buttons.................................................................................................. 119

What action buttons do................................................................................................................................................. 119
Add to a worksheet........................................................................................................................................................120
Run a process........................................................................................................................................................... 121
Navigate to another worksheet................................................................................................................................121
Run a process and navigate to a worksheet............................................................................................................ 124
Recalculate or rebuild a worksheet......................................................................................................................... 124
Set the appearance.................................................................................................................................................. 125
Edit, copy, rename, or delete.........................................................................................................................................125
Chapter 8. IBM API............................................................................................................ 127

Set up............................................................................................................................................................................. 127
Log automation activities and errors.............................................................................................................................128
Global API functions ..................................................................................................................................................... 128
ClearAllData .............................................................................................................................................................128
ClearBook................................................................................................................................................................. 128
ClearCache............................................................................................................................................................... 129
ClearSelection.......................................................................................................................................................... 129
ClearSheet................................................................................................................................................................ 129
HttpLogonCredentials.............................................................................................................................................. 129
Logoff ....................................................................................................................................................................... 130
Logon........................................................................................................................................................................ 130
Publish...................................................................................................................................................................... 131
RefreshAllData .........................................................................................................................................................132
RefreshAllDataAndFormat....................................................................................................................................... 132
RefreshSelection...................................................................................................................................................... 133
RefreshSheet............................................................................................................................................................ 133
SuppressMessages...................................................................................................................................................133
TraceError.................................................................................................................................................................133
TraceLog .................................................................................................................................................................. 134
UnlinkAllData ...........................................................................................................................................................134
UnlinkBook .............................................................................................................................................................. 135
ClearBook................................................................................................................................................................. 135
UnlinkSheet ............................................................................................................................................................. 135
UpdateServerUrl.......................................................................................................................................................135
Wait...........................................................................................................................................................................136
Exploration API functions .............................................................................................................................................137
Clear..........................................................................................................................................................................137
v
Create....................................................................................................................................................................... 137
CreateFromMDX....................................................................................................................................................... 138
GetColumnSuppression........................................................................................................................................... 138
GetRowSuppression.................................................................................................................................................138
GetValue................................................................................................................................................................... 139
Refresh..................................................................................................................................................................... 139
SwapRowsAndColumns........................................................................................................................................... 139
SetRowSuppression................................................................................................................................................. 140
SetColumnSuppression............................................................................................................................................140
Unlink........................................................................................................................................................................140
SetSpecification....................................................................................................................................................... 141
SetValue....................................................................................................................................................................141
Quick Report API functions .......................................................................................................................................... 142
Clear..........................................................................................................................................................................142
ColumnHierarchies...................................................................................................................................................142
Commit..................................................................................................................................................................... 143
Create....................................................................................................................................................................... 143
CreateFromMDX....................................................................................................................................................... 144
Cube..........................................................................................................................................................................144
DataSource............................................................................................................................................................... 145
EnableIndents.......................................................................................................................................................... 145
GetTuple................................................................................................................................................................... 145
GetSpecification....................................................................................................................................................... 146
GetReport................................................................................................................................................................. 146
ID.............................................................................................................................................................................. 147
Name........................................................................................................................................................................ 147
RebuildSpecification................................................................................................................................................ 147
Rebuild......................................................................................................................................................................147
Refresh..................................................................................................................................................................... 148
Replace..................................................................................................................................................................... 148
RowHierarchies........................................................................................................................................................ 148
Select........................................................................................................................................................................149
SetSlicer................................................................................................................................................................... 149
SlicerHierarchies...................................................................................................................................................... 150
Dynamic Report API functions ................................................................................................................................150
Example - processing within VBA ........................................................................................................................... 151
Macro files................................................................................................................................................................ 151
Script files.................................................................................................................................................................152
Chapter 9. Tutorials........................................................................................................... 153

Get started..................................................................................................................................................................... 153
How do I add a system?........................................................................................................................................... 153
How do I connect to a data source?........................................................................................................................ 154
First assignment............................................................................................................................................................ 156
Views........................................................................................................................................................................ 157
Customize Exploration Views...................................................................................................................................158
Share your work....................................................................................................................................................... 163
Chapter 10. Examples and use cases.................................................................................. 165

Work with items in an Exploration View........................................................................................................................165
Work with relational Exploration Views...................................................................................................................165
Sets........................................................................................................................................................................... 166
Nest columns or rows in an Exploration View......................................................................................................... 166
Example - evaluate revenue from specific order methods..................................................................................... 167
Work with items in a list.................................................................................................................................................168
Example - create a list report ..................................................................................................................................168
vi
Chapter 11. Troubleshoot...................................................................................................171
Troubleshoot a problem................................................................................................................................................ 171
Get fixes......................................................................................................................................................................... 172
Contact IBM Support..................................................................................................................................................... 172
Exchange information with IBM.................................................................................................................................... 173
Send information to IBM Support............................................................................................................................173
Receive information from IBM Support...................................................................................................................174
Subscribe to Support updates ......................................................................................................................................174
Common errors.............................................................................................................................................................. 175
Configuration Issues................................................................................................................................................ 175
Processing issues..................................................................................................................................................... 177
Security Issues......................................................................................................................................................... 178
Cognos Office Numbered Error Messages...............................................................................................................178
IBM Planning Analytics for Microsoft Excel numbered error messages.................................................................180
Microsoft Excel limits.....................................................................................................................................................181
Appendix A. Sample reports and packages......................................................................... 183

The Sample Outdoors Company....................................................................................................................................183
The Sample Outdoors Group of Companies................................................................................................................. 183
Employees......................................................................................................................................................................185
Sales and marketing...................................................................................................................................................... 185
Sample Outdoors database, models, and packages.................................................................................................... 185
Samples in the GO Data Warehouse (analysis) package.............................................................................................. 187
Employee Satisfaction Workspace.......................................................................................................................... 187
Return Quantity by Order Method............................................................................................................................187
Return Quantity by Product Line Chart.................................................................................................................... 187
Revenue Data Workspace........................................................................................................................................ 187
Samples in the GO Data Warehouse (query) package..................................................................................................187
Baselines.................................................................................................................................................................. 188
Bursted Sales Performance Report......................................................................................................................... 188
Samples in the Sales and Marketing (Cube) package...................................................................................................188
Revenue by Product Brand...................................................................................................................................... 188
Samples in the GO Sales (analysis) package................................................................................................................ 188
Sales Summary.........................................................................................................................................................188
Samples in the GO Sales (query) package.................................................................................................................... 189
Horizontal Pagination............................................................................................................................................... 189
No Data..................................................................................................................................................................... 189
Appendix B. Accessibility features..................................................................................... 191

Keyboard navigation...................................................................................................................................................... 191
Interface information.................................................................................................................................................... 195
Increase font size for future sessions..................................................................................................................... 195
View explorations in Windows high contrast mode................................................................................................ 195
Vendor software.............................................................................................................................................................195
IBM and accessibility.....................................................................................................................................................195
Appendix C. Rebrand Cognos Office Components................................................................197

Resource Files................................................................................................................................................................197
Run Cognos Office components in English in a localized Microsoft Windows environment....................................... 198
Rebrand or Localize Cognos Office Components .........................................................................................................199
Editing the resource (.resx) files.............................................................................................................................. 199
Compile the updated resource files.........................................................................................................................200
Test your work.......................................................................................................................................................... 200
Appendix D. Settings in the CognosOfficeReportingSettings.xml file....................................201
vii
Notices.............................................................................................................................. 209
Index......................................................................................................................................................................................... 213
viii
Introduction
IBM® Planning Analytics for Microsoft Excel is a Microsoft Excel-based tool that professional report authors use to build
sophisticated, multiple-sheet, multiple-query reports against multiple databases.
Audience
This guide assumes that you are familiar with IBM Cognos® products, such as IBM Cognos for Microsoft Office, and IBM
TM1®. You should also be familiar with Microsoft Office applications, such as Microsoft Excel.
Finding information
To find product documentation on the web, including all translated documentation, access IBM Knowledge Center
(http://www.ibm.com/support/knowledgecenter).
Accessibility features
Accessibility features help users who have a physical disability, such as restricted mobility or limited vision, to use
information technology products. IBM Planning Analytics for Microsoft Excel has accessibility features. For information
on these features, see the accessibility section in this document. For more information about the accessibility features
in IBM Planning Analytics for Microsoft Excel, see Appendix B, “Accessibility features,” on page 191
IBM Cognos HTML documentation has accessibility features. PDF documents are supplemental and, as such, include
no added accessibility features.
Forward-looking statements
This documentation describes the current functionality of the product. References to items that are not currently
available may be included. No implication of any future availability should be inferred. Any such references are not a
commitment, promise, or legal obligation to deliver any material, code, or functionality. The development, release, and
timing of features or functionality remain at the sole discretion of IBM.
Samples disclaimer
The Sample Outdoors Company, Great Outdoors Company, GO Sales, any variation of the Sample Outdoors or Great
Outdoors names, GO New Stores, Planning Sample, and SData depict fictitious business operations with sample data
used to develop sample applications for IBM and IBM customers. These fictitious records include sample data for sales
transactions, product distribution, finance, and human resources. Any resemblance to actual names, addresses,
contact numbers, or transaction values is coincidental. Other sample files may contain fictional data manually or
machine generated, factual data compiled from academic or public sources, or data used with permission of the
copyright holder, for use as sample data to develop sample applications. Product names referenced may be the
trademarks of their respective owners. Unauthorized duplication is prohibited.
© Copyright IBM Corp. 2009, 2017 ix

x Planning Analytics for Microsoft Excel Version 2.0.0 : User Guide
Chapter 1. What's new in IBM Planning Analytics for
Microsoft Excel
There are new features in IBM Planning Analytics for Microsoft Excel. For more information, see the IBM Planning
Analytics for Microsoft Excel documentation on the IBM Knowledge Center (http://www.ibm.com/support/
knowledgecenter/SSD29G_2.0.0).
2.0.25 - Feature updates, September 12, 2017

IBM Planning Analytics for Microsoft Excel was refreshed on September 12, 2017 to include bug fixes.To see the fix list,
click here: http://www-01.ibm.com/support/docview.wss?uid=swg27049597
2.0.23 - Feature updates, July 21, 2017

IBM Planning Analytics for Microsoft Excel was refreshed on July 21, 2017 to include bug fixes.To see the fix list, click
here: http://www-01.ibm.com/support/docview.wss?uid=swg27049597
2.0.22 - Feature updates, June 23, 2017

IBM Planning Analytics for Microsoft Excel was refreshed on June 23, 2017 to include bug fixes.To see the fix list, click
2.0.21 - Feature updates, June 2, 2017

IBM Planning Analytics for Microsoft Excel was refreshed on June 2, 2017 to include bug fixes.To see the fix list, click
here: http://www-01.ibm.com/support/docview.wss?uid=swg27049597#20r21.
2.0.20 - Feature updates, May 13, 2017

IBM Planning Analytics for Microsoft Excel was refreshed on May 13, 2017 to include bug fixes.To see the fix list, click
2.0.18 - Feature updates, April 8, 2017

IBM Planning Analytics for Microsoft Excel was refreshed on April 8, 2017 to include bug fixes.To see the fix list, click
2.0.0 - Feature updates, December 16, 2016

IBM Planning Analytics for Microsoft Excel was refreshed on December 16, 2016 to include the following new features.
New branding, look and feel

IBM Cognos Analysis for Microsoft Excel has been rebranded as IBM Planning Analytics for Microsoft Excel to reflect a
close relationship with IBM Planning Analytics Workspace. This includes the adoption of the IBM Planning Analytics
Workspace set editor and cube viewer functionality.
The following features have also been rebranded:
© Copyright IBM Corp. 2009, 2017 1

Terms in IBM Cognos Analysis for Microsoft Excel Terms in IBM Planning Analytics for Microsoft Excel
Crosstabs Exploration Views
Flex Views Quick Reports
Formulas Custom Reports
Static Snapshot
The toolbar and icons have also been given a makeover so that the functions that you use the most are more clearly
accessible to you. The new look and feel also gives greater consistency with other IBM Planning Analytics products.
Changed task pane

The IBM Cognos Analysis pane has been redesigned and renamed to the IBM task pane.
There are now two tabs, the first tab contains the data source tree. The source tree displays the cubes, views,
dimensions, levels, sets and other related objects from the TM1 server. You use the data in the source tree to create
Exploration Views and reports.
The second tab is the Workbook tab. This contains the Dynamic Reports, Exploration Views, Action buttons and Quick
reports that have been created. You can perform actions such as convert the Exploration View or report to a snapshot,
set properties, clear and refresh data.
Improved support of IBM Cognos TM1 Perspectives features

Dynamic reports
You can now create and work with Dynamic Reports in IBM Planning Analytics for Microsoft Excel. Dynamic reports
were called Active forms in Cognos TM1 Perspectives. Dynamic Reports enable you to combine TM1 functionality
with Microsoft Excel features and offer dynamic formatting.
Worksheet functions
The following worksheet functions are now available:
• TM1ELLIST: returns a set of element values from a TM1 model by using a single formula.
• TM1GLOBALSANDBOX: returns the current global active sandbox that was selected from the toolbar.
• TM1INFO: returns information about the current TM1 version and client.
• TM1PRIMARYDB: returns the primary TM1 server name that the user is authenticated through, even if the user is
implicitly logged into multiple TM1 servers.
Action buttons
Action buttons were introduced in the cloud-only release of IBM Cognos Analysis for Microsoft Excel version 10.3.
With this release, you can upgrade TM1 Perspectives Action buttons in the Options screen.
Shared components with IBM Planning Analytics Workspace

Set editor
IBM Planning Analytics for Microsoft Excel now uses the same set editor as used in IBM Planning Analytics
Workspace.
Cube viewer
Using the cube viewer, you can have multiple cube views open at the same time. You can also create Exploration
Views, Quick Reports, Dynamic Reports or Custom Reports from cube views.
You can work with data using the cube viewer rather than the Microsoft Excel grid.
Support for multiple hierarchies

Exploration Views and Quick Reports can display more than one hierarchy in a dimension.
2 Planning Analytics for Microsoft Excel Version 2.0.0 : User Guide

Note: Hierarchies can be viewed in IBM Planning Analytics for Microsoft Excel, however, you cannot create hierarchies
in IBM Planning Analytics for Microsoft Excel, you can create hierarchies in Planning Analytics Workspace, or by using
TurboIntegrator processes or TM1 REST API. For more information, see the the IBM Knowledge Center (http://
www.ibm.com/support/knowledgecenter/SSD29G_2.0.0).
Support for security authentication modes

IBM Planning Analytics for Microsoft Excel supports security authentication modes 1, 2, 3, 4, 5. Previous versions
supported modes 1 and 5. For information about configuring security, see Planning Analytics Installation and
Configuration documentation.
Forms based authentication (FBAC) is no longer supported for IBM Planning Analytics servers in IBM Planning Analytics
for Microsoft Excel.
Quick Reports available in Cognos TM1 Web and IBM Planning Analytics Workspace
You can publish Quick Reports to a TM1 Server and they are available as live websheets in Cognos TM1 Web and IBM
Planning Analytics Workspace. Live websheets maintain their connections to the TM1 server. If the data on the server
changes, the websheets reflects the change.
Add new connections from the Connect button

You can now add new connections to servers directly from the Connect button on the IBM Planning Analytics tab.
New API functions

This version adds new support and documentation for exploration, Quick Report, and Dynamic Report Application
Programming Interface (API) functions.
New settings in the Options screen

You can set more options in the Options screen instead of updating the configuration file manually.
The additional generic options that you can set are:
Default expand direction
You can now set the default expand direction when you double click.
Auto spread consolidated input
You can automatically convert values entered in consolidated cells into proportional spread operations.
Prompt for uncommitted changes
You can enable a confirmation prompt which appears before a refresh is performed.
The additional options for Exploration or list settings are:
Expand with double-click
You now have the option to expand consolidated members by double clicking on them.
Allow sum on context dropdown
You can now enable a 'Sum' button in the context dimension drop down. This feature allows you to easily select all
of the items in the dimension drop down.
Context member dropdown limit
You can define the number of members shown when expanding a context drop down.
The additional options for Quick report settings are:
Use level based indents
You can enable level based indentation in Quick Reports.
Formula writeback is enabled by default

You no longer need to manually enable formula writeback. This feature is now enabled by default.
What's new in IBM Planning Analytics for Microsoft Excel 3

Chapter 2. Get started
IBM Planning Analytics for Microsoft Excel is a Microsoft Excel-based tool that professional report authors use to build
reports using data sources from IBM Planning Analytics.
Use the interactive drag-and-drop environment in IBM Planning Analytics for Microsoft Excel to explore and analyze
data to find answers to business questions.
You can perform the following tasks:
• Find and focus on items that are important to your business.
• Understand trends and anomalies.
• Compare data, such as details to summaries, or actual results to budgeted results.
• Assess performance by focusing on the best or worst results.
• Share your findings with others.
You can use IBM Planning Analytics for Microsoft Excel for multidimensional analysis and exploration of large data
sources within the familiar Excel environment.
Get oriented
When you start Microsoft Excel after you have installed IBM Planning Analytics for Microsoft Excel, you will see a tab
that is called IBM Planning Analytics in the ribbon. The IBM Planning Analytics tab is your starting point for working
with IBM TM1 data in Microsoft Excel. When you log on to an IBM TM1 system and create reports, you see other user
interface features for working with IBM TM1 data.
The IBM Planning Analytics for Microsoft Excel user interface includes the IBM Planning Analytics tab, the IBM task
pane, which contains a source tree and several commands.
Watch this video on getting oriented:

Figure 1: IBM Planning Analytics for Microsoft Excel user interface
The following legend describes the areas that are referenced in the previous image:
1. IBM Planning Analytics tab
2. Overview area
3. IBM Task pane
4. Source tree
5. Work area
IBM Planning Analytics tab
The IBM Planning Analytics tab in the ribbon displays commands for starting IBM Planning Analytics for Microsoft
Excel, logging on to IBM TM1 systems, setting options, opening reports that are published to an IBM TM1 Server
Application Folder, and so on.
IBM task pane
The IBM task pane consists of two tabs:
• The first tab contains the source tree and controls for opening data sources.
• The Workbook tab contains the components of the active workbook. For example, any Exploration Views, Quick
Reports or Dynamic Reports that the workbook contains are listed.
The IBM task pane opens when you start IBM Planning Analytics for Microsoft Excel. You can move and resize the
pane.
The source tree displays the data sources that you selected.
• For TM1 data sources, the tree displays the cube, with its associated dimensions, members, and levels. The
source tree also displays saved views and TurboIntegrator processes.
You can add objects to a report by dragging them from the source tree to a worksheet.
The names of the dimensions, levels, and members in a data source come from the model. It is the responsibility of
the modeler to provide meaningful names that you can use when you create reports.

Overview area
The overview area is displayed when you are viewing an Exploration View or a list. Use the overview area as a
convenient place to quickly explore and change the contents of the Exploration View or list.
For Exploration Views, the overview area displays the Rows, Columns, and Context areas. You populate the
Exploration View with data by adding items from the data source to these areas. For example, you can place a
Department dimension in the rows and a Source dimension in the columns. The items that you place in the context
area are used to filter the values. For example, you can filter the Exploration View to display data for a specific year
by selecting a year in the Time dimension. Each box in the rows, columns, and context area represents a set of data
in the data source.
Work area
The work area is a Microsoft Excel worksheet where you create and view reports.
When you create a new Exploration View or list, the work area displays a visual guide to help you build the report.
Drop zones show you where you can drag items from the source tree to create the report. You can change, limit, or
expand the items that you see in an Exploration View by using techniques such as filtering and drilling, to quickly
focus on the most significant items on your worksheet.
If you want to use a more flexible report layout, rather than visual guides, you can create other types of reports
such as Quick Reports, Dynamic Reports, and Custom Reports.
Before you begin

Before you use IBM Planning Analytics for Microsoft Excel, check the following requirements.
Configure antivirus software

To run Planning Analytics for Microsoft Excel, you must first configure your antivirus software to allow connections from
both Microsoft .NET Runtime and Microsoft Excel. For more information, see Planning Analytics Installation and
Configuration (Local only) (https://www.ibm.com/support/knowledgecenter/SSD29G_2.0.0/
com.ibm.swg.ba.cognos.tm1_inst.2.0.0.doc/t_tm1_inst_prereq_av.html).
Set up connections for TM1 Rest APIs

IBM Planning Analytics for Microsoft Excel requires the use of TM1 REST APIs in IBM TM1 Server. An administrator may
need to configure the HTTP port number in the IBM TM1 Server configuration files for each TM1 Server. For more
information, see Planning Analytics Installation and Configuration (Local only) (http://www.ibm.com/support/
knowledgecenter/SSD29G_2.0.0/com.ibm.swg.ba.cognos.tm1_inst.2.0.0.doc/t_ug_cxr_odata_config.html).
Internet browser requirements

IBM Planning Analytics for Microsoft Excel requires Internet Explorer 11.
Upgrade existing workbooks

If you have workbooks from earlier versions, update the original connections to the TM1 server to the Planning
Analytics Workspace URI by editing the connections in the Options screen. For more information, see “Update
Connection URLs” on page 23.
You should also update connections to Exploration Views and Quick Reports by using the Update connection utility. For
more information, see “Utilities” on page 25.
Start IBM Planning Analytics for Microsoft Excel

When you first open Microsoft Excel, an IBM Planning Analytics tab is displayed in the ribbon.
Procedure
1. Start Microsoft Excel or open a Microsoft Excel spreadsheet.
Get started 7
2. Click the IBM Planning Analytics tab, and then click Task Pane.
The IBM pane is displayed.
If the IBM Planning Analytics tab is not displayed on the ribbon, see “The Cognos Office interface fails to initialize
in Microsoft Office ” on page 176.
What to do next
To start working with IBM Planning Analytics for Microsoft Excel, you must configure connections to servers. See “Set
up a connection” on page 15
The IBM Planning Analytics tab

After starting IBM Planning Analytics for Microsoft Excel, an IBM Planning Analytics tab is displayed in the ribbon. You
might decide to resume work on non-IBM TM1 workbooks, and want to show only Microsoft Excel commands and
buttons. You can customize the ribbon to hide the IBM Planning Analytics tab.
Procedure
1. To hide the IBM Planning Analytics tab in Microsoft Office 2010 or 2013, click File, Options, and then Customize
Ribbon.
2. Under Customize the Ribbon, clear the IBM Planning Analytics check box.
3. Click OK.
To hide the IBM Planning Analytics tab in earlier versions of Microsoft Office, click Tools > Customize.
• To show or hide the IBM pane, select or clear the IBM check box.
• To show or hide the IBM Planning Analytics tab, select or clear the IBM Cognos for Microsoft Office check box.
Report types
IBM Planning Analytics for Microsoft Excel offers you the flexibility to create various report types, from simple lists and
Exploration Views to complex formula-based reports.
The report types that you can use depend on whether you are using an IBM TM1 data source or an IBM Cognos
Analytics package.

Figure 2: Report types
If you have both TM1 and IBM Cognos Analytics available, you can create workbooks that contain both TM1 and IBM
Cognos Analytics reports. For example, you can create an Exploration View that shows sales by product line and then
create a Quick Report that shows budget projections by product line. You can then create Microsoft Excel calculations
that reference cells in the two reports.
You can also combine TM1 and IBM Cognos Analytics data in a single report by using formulas. For example, you can
create a cell-based report that uses a IBM Cognos Analytics package, add TM1 formulas, and then use the IBM Cognos
Analytics and TM1 data in Microsoft Excel calculations.
Planning Analytics for Microsoft Excel report types

When you are using data from an IBM Planning Analytics data source, you can work in multiple ways: Exploration
Views, lists, Quick Reports, Dynamic Reports, or Custom Reports (reports based on formulas). You can use multiple
types of report in a workbook. Each report type has its own benefits and limitations.
Lists
A list shows data in rows and columns. Each column shows the members of a dimension or set.
When you create a list, you use a single drop zone, columns, to create a list of members. A drop zone is an area where
you can drag items to include in a report. You can add more columns to populate the list with additional information.
Use list explorations to show detailed information from a data source, such as customer lists or product lists.
You can also create a list to look up the value of a member, and then use the value in another worksheet, for example.
Some of the strengths that are associated with lists include drag-and-drop capabilities and visual cues that are
provided by the zone in the overview area. With lists, you can view all of the members in a dimension or set easily and
quickly.
Use a list:
Get started 9
• To create a list of members in a dimension
Exploration Views
An Exploration View shows data in rows and columns. An Exploration View also has a context area, which you can use
to filter the data in the Exploration View.
When you create an Exploration View, you use drop zones to add objects from the source tree to the rows, columns,
and context area of the report. A drop zone is an area where you can drag items to include in a report.
Some of the strengths that are associated with Exploration Views include drag-and-drop capabilities and visual cues
that are provided by the drop zones in the overview area.
Use Exploration Views to compare and manipulate data so that you can better understand relationships between data
and the relative importance of individual data items.
For example, you look at revenue for the years 2012 - 2015 by sales region. You notice a dip in the revenue for 2014.
You focus the Exploration View on 2014 only and expand 2014 to show revenue results by quarter. You then replace
the sales region dimension with the products dimension to explore revenue in 2014 from a different perspective.
Use an Exploration View:
• To find answers to simple questions that can be found in your data source, such as the revenue for Tents in the
Americas for 2015
• To build interactive Exploration Views that you or another user can drill up and down in
• When you are not concerned with formatting
• To build a data set to convert and use in a more complex analysis, such as a formula-based report or a Dynamic
Report
Quick Reports
A Quick Report shows data in rows and columns. A context area above the Quick Report shows the context members.
When you use Quick Reports, you drag-and-drop objects onto the regions of the report: rows, columns, context, and
data. You can create Quick Reports by using existing Exploration Views or views. You can create multiple Quick Reports
on a worksheet. You can also use multiple data sources.
For example, you create three Quick Reports on a worksheet to show different views of financial performance by region.
You then add a fourth Quick Report that uses a different IBM Planning Analytics data source. You then create a
Microsoft Excel calculation that references cells in the four Quick Reports to add more information to the report.
Some of the strengths that are associated with Quick Reports include the ability to present multiple views that use the
same or different data sources in a worksheet, the ability to build complex layouts, and the ability to add Excel
calculations, charts, and formatting. With Quick Reports, you can move beyond simple Exploration View layouts while
still having the advantage of visual cues provided through the Quick Report regions.
Use Quick Reports:
• To build complex, highly formatted reports
• To use multiple data sources or servers
• When the row and column definitions will not change
Custom Reports
When you use Custom Reports, you use TM1 worksheet functions to build the report. You can create a Custom Reports
report from scratch, you can build an Exploration View or Quick Report and convert it to formulas, or you can create
Custom Reports from a vube view.
Some of the strengths that are associated with Custom Reports include the ability to use multiple data sources in the
same worksheet; the ability to move cells, rows, and columns; and the ability to add Excel calculations, charts, and
formatting. With formula-based reports, you can move to a custom or complex layout.
Use Custom Reports reports:
• To build a complex report that cannot be easily achieved with Quick Reports or Dynamic Reports

• To work with data from multiple servers and data sources in a report
• When formatting is important
Dynamic Reports
A Dynamic Report shows data in rows and columns. A context area above the Dynamic Report shows the context
members. Dynamic Reports use TM1 functions to define the components of the report, such as context members, row
members, and display properties. Dynamic Reports also use formulas to apply formatting to rows automatically. You
can create a Dynamic Report from scratch or by converting an Exploration View to a Dynamic Report.
Some of the strengths that are associated with Dynamic Reports include the ability to have dynamic row members with
customized formatting, the ability to expand and collapse rows, and the ability to use Excel calculations and other Excel
features in the report. With Dynamic Reports, you can create more complex reports while still using interactive
features, such as expanding and collapsing rows.
Use Dynamic Reports:
• To build a complex report that cannot be easily achieved with Quick Reports
• To apply formatting automatically to rows
Connect to TM1
You can connect to IBM Planning Analytics data that is configured to be accessible from IBM Planning Analytics
Workspace local version 2.0.0 or later.
A modeler uses a modeling application, such as IBM Cognos Performance Modeler, to create a data source. A data
source includes a cube and related items, such as saved views and processes for automating tasks. The data source
also defines security privileges for working with the data source. The modeler publishes the data source to a Planning
Analytics server.
In the IBM Planning Analytics Workspace Administration tool, the administrator configures the Planning Analytics URIs
and authentication servers.
To work with a Planning Analytics data source, you connect to IBM Planning Analytics Workspace URL, for example
http://<host-name>/, log on to the Planning Analytics server, and then select a data source. You can use the data
source to create your own reports. You can also open workbooks that are published on the Planning Analytics server.
You can explore the data and save your work locally. You can also publish your workbooks to the Planning Analytics
server and share them with other users.
You can also modify Planning Analytics data. For example, when your Planning Analytics administrator distributes an
enterprise-wide budget plan, you can use IBM Planning Analytics for Microsoft Excel to create an Exploration View to
review, analyze, and update the portion of the plan that is assigned to you.
IBM TM1 worksheet functions are available to you IBM Planning Analytics for Microsoft Excel. You can use the
functions to retrieve data from the data source and to write values back to the data source.
If the modeler includes TurboIntegrator processes in the data source, you can use them in IBM Planning Analytics for
Microsoft Excel. For example, you can add an action button to a worksheet and configure it to run a TurboIntegrator
process. You can also run processes from the source tree.
Notes for IBM TM1 Perspectives users

If you use IBM TM1 Perspectives, you will notice some differences and improvements in IBM Planning Analytics for
Microsoft Excel.
Note: IBM Planning Analytics for Microsoft Excel and IBM TM1 Perspectives should not both be enabled concurrently in
Microsoft Excel. Doing so may result in some features not working.
The benefits of using IBM Planning Analytics for Microsoft Excel include the following:
• IBM Planning Analytics for Microsoft Excel reports are designed to work well even in a wide area network
environment, without the need for Citrix.
Get started 11
• IBM Planning Analytics for Microsoft Excel offers the following improvements to formulas:
– DBR is equivalent to DBRW and DBS is equivalent to DBSW. DBR, DBRW, DBS, DBSA, and DBRA are optimized to
reduce network traffic and improve performance on wide area networks.
– If a SUBNM formula references a set, a drop-down arrow is displayed when you click the SUBNM cell. You can use
the drop-down list to select a different member in the set. You must be logged on to the TM1 server to use this
feature.
– You can modify multiple DBR and DBRW formulas by selecting a range of cells and then modifying the formula
parameters in the Function Editor.
– The TM1USER function returns the user name, not the internal CAMID.
– IBM Planning Analytics for Microsoft Excel distinguishes between member names in formulas that include or do
not include spaces. TM1 Perspectives does not. For example, TM1 Perspectives interprets Version1 and
Version 1 as the same member in formulas.
• You can copy and paste values multiple times in IBM Planning Analytics for Microsoft Excel. In TM1 Perspectives, you
can copy only once, and then the clipboard is empty. You can also copy and paste values across multiple cells in IBM
Planning Analytics for Microsoft Excel.
• IBM Planning Analytics for Microsoft Excel uses named styles, which means you can customize the appearance of
your reports easily.
• Reports that you open from the Application folder on an IBM TM1 server open with their actual names and not a
generated random name.
Some TM1 Perspectives features are implemented differently in IBM Planning Analytics for Microsoft Excel:
• Instead of slicing from the Cube Viewer into an Excel worksheet, in IBM Planning Analytics for Microsoft Excel you
can right-click a view and insert it as the type of report you want. If you want to manipulate the view first, insert it as
an Exploration View, manipulate the view, and then convert it to the type of report you want.
• When you refresh a Dynamic Report, the formatting is updated only if the number of rows in the data area has
changed or if a value in the ID column of the format range has changed. Otherwise, rebuild the Dynamic Report (ALT
+F9) to update the formatting. In TM1 Perspectives, the formatting is updated when you recalculate (F9) a Dynamic
Report.
• When you rebuild a Dynamic Report, rows and columns are inserted or deleted from the existing rows or columns. In
TM1 Perspectives, all rows and columns are deleted and then re-added.
• In Dynamic Reports, any change to the header row (the row with the TM1RPTROW formula) of the report requires a
repair. For example, if you change the formula or add a new column, you must repair the Dynamic Report to see the
results.
• In Dynamic Reports with nested rows, the member names in the nested rows are not grouped. Instead, the member
names are repeated.
• Zero suppression is done based on the column tuples that are present. In TM1 Perspectives, zero suppression is done
based on the product of the members of each dimension on the column (symmetric column).
• The TM1RPTELLEV function returns the level of a member in a dimension. In TM1 Perspectives, TM1RPTELLEV
returns the level of a member within a set.
Some TM1 Perspectives features are not implemented in IBM Planning Analytics for Microsoft Excel:
• Modeling is not available in IBM Planning Analytics for Microsoft Excel. Instead, use a modeling tool, such as IBM
Cognos TM1 Performance Modeler to create and maintain models, applications, and security permissions.
• F9 does not refresh TM1 data.
• The TM1 macro functions are not available in IBM Planning Analytics for Microsoft Excel. Instead, you can use the
Application Programming Interface (API).
• Dynamic Reports are not supported.
• TM1 worksheet functions are supported in IBM Planning Analytics for Microsoft Excel, except for the following
features:
– Data spreading in DBR and DBRW formulas
– Pick lists in formulas
– Functions for Dynamic Reports
• Writeback mode for formulas is enabled by default in the IBM Planning Analytics for Microsoft Excel configuration file.

• The following data spreading methods are not available in IBM Planning Analytics for Microsoft Excel: Relative
Proportional Spread, Relative Percent Adjustment.
• Dynamic Reports are supported in IBM Planning Analytics for Microsoft Excel, except for the following features:
– A user interface to create multiple Dynamic Reports on the same worksheet
– Cell protection and password protection
– Expand Above
Enable trust access to the VBA project object model

Trust access to the VBA project object model is required for IBM Planning Analytics for Microsoft Excel. Macros
developed for IBM Planning Analytics for Microsoft Excel may not work properly if trust access to the VBA project
object model is not granted.
Procedure
1. Start Microsoft Excel.
2. Open a workbook.
3. Click File and then Options.
4. In the navigation pane, select Trust Center.
5. Click Trust Center Settings....
6. In the navigation pane, select Macro Settings.
7. Ensure that Trust access to the VBA project object model is checked.
8. Click OK.
Results
Trust access to the VBA project object model will be granted for IBM Planning Analytics for Microsoft Excel.
Open an IBM TM1 Perspectives workbook

You can open an IBM TM1 Perspectives workbook in IBM Planning Analytics for Microsoft Excel.
About this task

Before you open a TM1 Perspectives workbook, note the following points:
• If you open a workbook on a IBM Planning Analytics and convert it, you must publish the converted workbook to
make it available on the server.
• If the workbook contains action buttons, you are asked if you want to convert them. If you choose to convert them, a
backup copy of the workbook is saved, and then a conversion process runs.
• You cannot edit or use an action button that was created in TM1 Perspectives unless you covert it.
• Dynamic Reports are not supported. The formula cells display #NAME! or #VALUE! when you open the workbook.
• Background images are not maintained.
Procedure
2. Open a TM1 Perspectives workbook.
3. If you are prompted to convert action buttons, select an option and click OK.
4. If you are prompted for the host, either select a TM1 system from the list or type the system URL, and then click OK.
The format of the URL is http://[server]:[port number], for example http://myserver:9510
5. Log on to the TM1 server.
Results
The report is displayed in IBM Planning Analytics for Microsoft Excel. The formulas in the report reference the TM1
system that you specified.
Get started 13
Upgrade IBM TM1 Perspectives action buttons
Upgrading IBM TM1 Perspectives action buttons allows them to be used in IBM Planning Analytics for Microsoft Excel.
About this task

When upgrading action buttons, note the following points:
• Trust access to the VBA project object model must be granted in Microsoft Excel. See “Enable trust access to the VBA
project object model” on page 13.
• You must have a TM1 Perspectives workbook that contains one or more action buttons.
• An administrator may upgrade action buttons in public and private workbooks.
• A non-administrator may only upgrade action buttons in private workbooks.
• Once action buttons are converted for use in IBM Planning Analytics for Microsoft Excel, they will no longer work in
TM1 Perspectives. It is recommended that a backup of all TM1 Perspectives workbooks is created before upgrading
action buttons.
Procedure
1. On the IBM Planning Analytics toolbar, click Options .

2. In the navigation pane, click IBM Planning Analytics.
3. Under Action Button Settings, click Upgrade Action Buttons.
4. Optional: Under Backup Excel Files, click Browse and define a backup directory. This step will create a backup of
the TM1 Perspectives workbooks.
5. Under Conversion Log, click Browse and define a log directory.
6. Click OK.
7. Using the drop down menu, select the system that contains a TM1 Perspectives workbook that needs to be
upgraded.
8. Select the server that contains a TM1 Perspectives workbook that needs to be upgraded.
9. Select a TM1 Perspectives workbook that contains the action buttons that need to be upgraded.
10.Click Upgrade.
11.Click OK.
Results
A dialog will indicate the number of files upgraded. In this instance, a file is a workbook that has had action buttons
within it upgraded for use in IBM Planning Analytics for Microsoft Excel.
Tip: By selecting the parent server or folder to upgrade, you can upgrade action buttons in multiple TM1 Perspectives
workbooks.

Chapter 3. Work with data and reports
You can connect to data sources and explore the data by using reports.
You can make changes to your reports by retrieving data and overriding any previous changes, removing data, or
converting dynamic data to static data to prevent future updates from the servers. You can also share your reports with
other users.
When you work with data from the IBM TM1 server, you are also able to write back data to the TM1 cube.
Set up a connection
To access content, you must configure connections to IBM TM1 systems. Contact your administrator to obtain the URLs
required to create connections.
To connect to IBM Planning Analytics data sources and reports and to publish reports to Application Folders, you must
connect to an IBM Planning Analytics Workspace URL.
This video demonstrates how to set up connections to systems.
https://youtu.be/BuPAfJIhO4o
Before you begin

You must contact your administrator for the URLs required to connect to IBM TM1 systems. Each URL is unique based
on system configuration.
• Example URL for a IBM Planning Analytics Workspace system:
http://computer_name
Computer_name is either the IP address of the computer or the computer name.
Procedure

2. In the navigation pane, click IBM.
3. Create a new connection or edit an existing connection.
• To create a new connection, click Add.
• To modify an existing connection, select the connection and then click Edit.
4. In the Datasource Type box, select the data source.
5. In the Connection URL box, type the URL provided by your administrator that identifies the location of the IBM TM1
system.
6. In the Friendly Name box, type a name.
7. Click Test Connection.
If the connection fails, contact your administrator to verify the connection information. See the troubleshooting
section for solutions to common configuration issues.
8. Click Save.
9. If you modified an existing connection, you must change the server and package information for each workbook.
For more information, see “Update Connection URLs” on page 23.
Results
The connection appears in the IBM connections list.

In IBM Planning Analytics for Microsoft Excel, the friendly name appears in the Connect drop-down on the ribbon.
Log on to a connection
IBM Planning Analytics for Microsoft Excel supports authenticated and anonymous user access. To use IBM TM1 as an
authenticated user, you must log on to the IBM TM1 system that contains the data source or package that you want to
use.
You can be logged on to multiple systems at one time.
You can also automate this task by using the Logon method. For more information, see “Logon” on page 130.
Procedure
1. On the IBM Planning Analytics tab, click Connect, and select the server that contains the data source you want to
use.
2. Type your User Name and Password, and click Login.
Results
You are logged on to the IBM TM1 system.
If you did not select a data source, you can open one. For more information, see “Open a data source ” on page 16.
Open a data source

Open the data source that you want to use with reports. You must have security rights to the data source.
For IBM TM1 systems, the data sources that you use to generate TM1 reports are based on models that are created in a
modeling tool, such as IBM Cognos TM1 Performance Modeler. A model consists of a cube and a set of related objects,
such as views, dimensions, and processes.
Before you begin

The data source must be previously created and published to the IBM TM1 system. For more information about
creating TM1 data sources, see the IBM Cognos TM1 Performance Modeler or the IBM Cognos TM1 Operation
documentation.
Procedure
2. Click the IBM Planning Analytics tab in the ribbon.
3. Click Task Pane.
4. In the Task Pane, click Open.

5. Select the system.
6. Click the data source you want to use.
• To open a IBM Planning Analytics, click a TM1 Server Application Folder. If prompted, log on to the server, and
then select a data source.
Tip: To refresh the list, click .
7. For TM1, you can choose to show control objects and processes. Click and select the required option.
8. Click OK.
Results
Objects from the selected data source or package, such as data items, appear in the source tree.

Refresh a data source or package
If a data source or package has changed recently, you can refresh the source tree to get the most recent version of the
data source or package.
For example, suppose a modeler has created a new view called Revised Budget Plan for the Base Sales Forecast cube
on the GO New Stores TM1 server. You want to use the new view in your workbook. When you refresh Base Sales
Forecast, the Revised Budget Plan view is available under Views in the source tree.
In the source tree, right-click the first node in the tree, and then click Refresh. The data source or package is refreshed
from the server.
Change the system and data source

You can change the IBM TM1 system that is used by a report. You can also change the data source that is used by a
report.
Refer to the following topics:
• For Exploration Views or lists, see “Change the system and data source used by an exploration” on page 51.
• For Quick Reports, see “Change the system and data source used by a Quick Report” on page 56.
• For TM1 formulas and Custom Reports, see “Change the server and data source of TM1 formulas” on page 105.
• For Dynamic Reports, see “Change the server and data source used by a Dynamic Report” on page 59.
Open and download workbooks

You can open workbooks that have been published to an IBM TM1 server.
You might have existing workbooks that you want to update. Your business situation may have changed and you now
want to apply various business scenarios. To refresh your data or make enhancements, you can open or download
published Microsoft Excel workbooks. You can then use MicrosoftExcel to make changes.
Settings for custom properties that were specified in earlier versions of IBM Planning Analytics for Microsoft Excel
workbooks become the new settings in the Options dialog box. For example, when an earlier version of an IBM
Planning Analytics for Microsoft Excel-enabled document is opened, the address for the gateway appears in the list of
addresses under IBM connections, if one was not already defined in custom properties.
Open a workbook from the TM1 Server Application Folder

You can store the workbooks that you create or modify on the TM1 Server Application Folder. You can also save those
workbooks on your computer. This is useful if you want to send a report to a report author who is working in a different
environment, or you want to save the report to a source code controlled directory on a local network or drive.
Before you begin

• Workbooks have been published to a public folder on a TM1 Server Application Folder.
• You know the TM1 system URL and the name of the TM1 Server Application Folder where workbooks are published.
Procedure
1. On the IBM Planning Analytics tab in the ribbon, click Open .

2. In the Open box, select the IBM TM1 system that contains the workbook that you want to open.
3. Select a TM1 Server Application Folder and log on, if prompted.
4. Navigate to the folder that contains the workbook you want to open.
Tip: To return to the list of servers on the TM1 system, click Servers.
5. Click the workbook, and click Open.
Work with data and reports 17

Results
The workbook opens. You can make changes, manipulate data, and publish it to TM1 Server Application Folder for
sharing.
Note: Opening a workbook with Protected View enabled may prevent Microsoft Excel from loading Planning Analytics
for Microsoft Excel styles. In order to ensure that Microsoft Excel loads Planning Analytics for Microsoft Excel styles in a
workbook with Protected View enabled, you should:
1. Save the workbook with Protected View disabled.
2. Close Microsoft Excel.
3. Open the workbook and launch Planning Analytics for Microsoft Excel.
4. Enable Protected View and save the workbook.
5. Close Microsoft Excel.
Find items in the source tree

The data source or package that you select might contain large amounts of data. You can use several techniques to find
the items in the source tree that you need.
You can do the following:
• Expand a dimension to see successive levels and details
• Specify a greater or lesser number of items to show in the source tree
• Search for items
By default, the source tree shows 50 items for any one dimension at a time. You can change this value to increase or
decrease the number of items displayed. Depending on the size of the data source, you might want to set a smaller
value to improve performance. For more information, see “Member display count limit” on page 26.
If you are using a IBM Planning Analytics data source and the number of members in the dimension is greater than the
member display limit, a More icon is displayed. If you click More, more members are displayed. For example, if the
member limit is 25 and you click More, another 25 members are displayed.
Search for members in an IBM Planning Analytics data source

When the source tree displays an IBM Planning Analytics data source, you can search for members in the data source
by name or by attribute values.
Procedure
1. In the source tree, select a hierarchy or member.
• To search all members in a hierarchy, select a hierarchy.
• To search a member and its descendants, select a member.
2. Right-click the hierarchy or a member, and click Search metadata.
3. Define the search criteria.
To add search criteria, click the plus sign at the end of the search criteria row. To delete a search criteria, click the
minus sign at the end of the row.
4. Click Apply.
The search results are displayed. You can drag members from the search results list to the work area.
5. After you finish your search, click OK.
Example
Suppose that you want to create an Exploration View that shows all Sedan car models that are also leaf members. You
want these members to be displayed in the rows of your Exploration View.
1. Open PriceCube on the SData server.
Note: SData is a sample TM1 Server Application Folder that is provided with TM1. PriceCube is a sample cube that
contains a Model dimension.

2. Create a blank Exploration View.
3. In the source tree, expand the Model dimension.
4. Right-click the model hierarchy and select Search metadata.
5. Create the search criteria.
• Select Name, Contains, and type Sedan.
• Click the plus sign to add another row.
• Select Level, =, and enter 0.
Name Contains Sedan

Level = 0
6. Click Apply. The results are displayed.
7. Select all the members that are returned by your search.
8. Drag the members to the Rows drop zone in the Exploration View.
The rows of your Exploration View now display Sedan car models that are leaf members in the Model dimension.
Refresh data
If the data in a report has changed, you can refresh the data to ensure that you are working with the latest data.
About this task

You can refresh your entire workbook, a worksheet, a report, or just selected cells.
• To update the entire workbook, on the IBM Planning Analytics tab, click Refresh All Data.
You can choose to Refresh the data only or Refresh the data and report formatting.
All worksheets, including Exploration Views, lists, and Custom Reports are updated with the most recent data.
If you choose to also refresh report formatting, formats are updated.
– Refreshing the report formatting applies only to Exploration Views and lists, and temporarily overrides the Run
with Excel formats option on the Exploration or List toolbar.
– Quick Reports update their formatting based on a per-Quick Report flag to use server formats (instead of the global
flag for explorations) and update formats every time the data is pulled.
– Custom Reports have no dynamic formatting component and use standard Excel formatting.
• To refresh only the current worksheet, right-click any cell on the worksheet, click IBM Planning Analytics > Refresh
> Refresh worksheet.
• To refresh a specific report, follow these steps:
– In an Exploration View or list, click and select an option.

– In a Quick Report, click .
– For a Dynamic Report, in the source tree, expand Dynamic Reports. Right-click the Dynamic Report and click
Refresh. For more information, see “Refresh, rebuild, or recreate” on page 57.
– For Custom Reports and cell-based reports, right-click any cell in the report, click IBM Planning Analytics >
Refresh > Refresh worksheet.
• To refresh only specific cells, right-click a cell or range of cells, click IBM Planning Analytics > Refresh > Refresh
selected cells.
Clear cell content

You can clear data from the cells in an exploration, cell-based analysis, or in Quick Reports.
The cleared cells remain as blank cells on the worksheet. Formats, such as number formats, conditional formats, and
borders are retained. Clearing the content does not break the link to the data source.

You might want to clear the data before you share a report so that
• Report consumers are required to refresh data to obtain recent changes from the data source
• Report consumers are authenticated before they are able to view report content
You can clear data from an entire workbook, a worksheet, a report, or selected cells.
• To clear all data in a workbook, on the IBM Planning Analytics tab on the ribbon, click Or, right-click any cell on a
worksheet, click IBM Planning Analytics > Clear data > Clear workbook.
• To clear all data only in the current worksheet, right-click any cell on the worksheet, click IBM Planning Analytics >
Clear data > Clear worksheet.
• To clear the data in a specific report, follow these steps:
– For an Exploration View or list, in the source tree, expand Current Explorations. Right-click the Exploration View or
list and click Clear Data.
– For a Quick Report, in the source tree, expand Quick Reports. Right-click the Quick Report and click Clear Data.
– For a cell-based report, right-click any cell on the worksheet, click IBM Planning Analytics > Clear Data > Clear
Worksheet.
Note: The Clear Data command does not clear data from Dynamic Reports or Custom Reports.
• To clear data only from specific cells, right-click a cell or range of cells, click IBM Planning Analytics > Clear Data >
Clear Selected Cells.
You can also automate this task by using the ClearAllData method. For more information, see “ClearAllData ” on page
128.
To restore the data, refresh the data. For more information, see “Refresh data” on page 19.
Note: Because of the way newer versions of Microsoft Excel open workbooks that were created in older versions of
Excel, some values are visible in a published and cleared workbook when it is opened in a newer version of Excel.
Opening the workbook in a newer version of Microsoft Excel triggers recalculation, which includes a refresh of the IBM
TM1 data. Data is authenticated with the credentials of the user that opens the workbook.
Convert dynamic data to snapshots (static data)

If you modify a workbook, worksheet, or exploration that you do not want to update with changes from the content
store, you can convert the dynamic data items to snapshots (static data) by disconnecting from the data source.
When you convert dynamic data to snapshots, any query-related information, such as calculations and filters, is
removed but the data values are preserved.
To convert all reports in a workbook to a snapshot, on the toolbar, click Snapshot > Convert Book to Snapshot.
To convert a worksheet to static data, right-click a cell and click IBM Planning Analytics > Convert to snapshot >
Convert worksheet to Snapshot.
To convert a cell or range of cells to static data, right-click a cell or a range and click IBM Planning Analytics > Convert
to snapshot > Convert Selected Cells to Snapshot.
To convert data in reports, follow these steps:
• For an Exploration View or list, in the source tree, expand Current Explorations. Right-click the Exploration View or
list and click Convert to snapshot. Or, to convert all Exploration Views and lists, right-click the Current Explorations
folder and click Convert all to Snapshots.
• For a Quick Report, in the source tree, expand Quick Reports. Right-click the Quick Report and click Convert to
snapshot. Or, to convert all Quick Reports, right-click the Quick Reports folder and click Convert to snapshot.
• For Custom Reports, Dynamic Reports, and cell-based reports, right-click any cell in the report, click IBM Planning
Analytics > Convert to snapshot > Convert worksheet to Snapshot.

Copy and move worksheets
You can copy or move worksheets that contain reports based on IBM TM1 data. You can copy or move worksheets
within a workbook or between workbooks.
Before you begin

If you want to copy a worksheet that contains a Quick Report, start IBM Planning Analytics for Microsoft Excel before
you copy or move the worksheet.
Procedure
1. Go to the worksheet that you want to move or copy.
2. Right-click the worksheet tab and click Copy.
3. Copy the worksheet.
For more information, see the Microsoft Excel online help.
Share your analysis

Share your analysis to give colleagues an opportunity to view important information or contribute their own pieces of
data.
Several options exist for storing and distributing IBM Planning Analytics for Microsoft Excel-enabled workbooks.
Publish a workbook to a TM1 Server Application Folder

You can publish workbooks that contain TM1 reports to a TM1 Server Application Folder. You can publish lists,
Exploration Views, Quick Reports, Dynamic Reports, and Custom Reports. Publish a workbook to share it with other
users.
This video demonstrates how to publish a workbook.
https://youtu.be/ddoDcJRohx0
About this task

When you publish a workbook, it is saved under the TM1 Server Application Folder. The Workbook can then be opened
in TM1 Web, and in IBM Planning Analytics Workspace.
By default, workbooks are published as private, unless you publish the workbook to a public folder or change the
workbook from private to public. Private workbooks are available only to you. Public workbooks are available to users
who have access permissions for the TM1 Server Application Folder where you published the workbook.
Lists and Exploration Views are displayed as static websheets in TM1 Web and IBM Planning Analytics Workspace. This
means that the data is not read from the TM1 Server Application Folder and so doesn't change when the data on the
server changes.
Custom Reports, Quick Reports, and Dynamic Reports are displayed as live websheets. A live websheet maintains its
connection to the TM1 Server Application Folder. If the data on the server changes, the live websheet reflects the
change.
You can use subfolders to organize workbooks. You can rename or delete folders and workbooks that you created.
For example, you can publish a workbook that is called Budget Plan to a TM1 Server Application Folder called Planning
Sample in a folder called Budget. In TM1 Web, you can open the budget plan report by connecting to the Planning
Sample server and navigating to Applications > Budget. The workbook is displayed in TM1 Web as a static websheet.
Procedure
1. On the IBM Planning Analytics tab, click Publish.

2. Select a TM1 connection.
3. Select a TM1 Server Application Folder.
4. Select a folder or create a new folder.
By default, new folders are private. To make a new folder available to others, an administrator needs to right-click
the folder and click Make Public.
5. Type a name for the workbook.
6. Optional: Enter a description.
7. Click Publish.
You can make a workbook public after you have published it. On the IBM Planning Analytics tab in the ribbon, click
Open. Locate the workbook, right-click it, and select Make Public.
Run Cognos TM1 TurboIntegrator processes

You can run IBM Cognos TM1 TurboIntegrator processes from IBM Planning Analytics for Microsoft Excel.
A TurboIntegrator process contains a script of TurboIntegrator functions and commands to programmatically import
data as well as create and modify TM1 objects, such as cubes and dimensions. An IBM TM1 administrator creates the
TurboIntegrator process and saves the process on an IBM TM1 server. The administrator also assigns security
privileges to the TurboIntegrator process. You must have read access privileges to access the TurboIntegrator process
from the source tree in IBM Planning Analytics for Microsoft Excel. You cannot create a TurboIntegrator process from
IBM Planning Analytics for Microsoft Excel.
You can run, monitor, and cancel TurboIntegrator processes directly from the source tree. You can also change
TurboIntegrator process parameters from the source tree.
Expand Processes in the source tree to see a list of available processes. Right-click a process and then click Edit
Parameters to edit it, or Run Process to run it.
By default, when a process is running, there is no progress indicator. To monitor the execution of running processes,
right-click Processes, and then click Active Processes. In the Active Processes window you can monitor process
execution, and also cancel running processes.
You can also create an action button that runs a TurboIntegrator process. For more information, see “Run a process” on
page 121.
For more information about TurboIntegrator processes, see the IBM Cognos TM1 TurboIntegrator documentation.

Chapter 4. Set options
You can set options that apply to IBM Planning Analytics for Microsoft Excel.
You can also set options that apply to specific explorations. For more information, see “Set properties” on page 50.
IBM settings
Start application
You can choose the startup application. Click the application icon that best meets your needs.
Procedure
1. On the IBM Planning Analytics tab on the ribbon, click Options .

3. Choose the startup application.
4. Click OK.
Update Connection URLs

If the URL of an IBM system changes, you can edit the information to use the new URL.
Editing the URL updates the saved connection for the IBM Planning Analytics for Microsoft Excel application, but not
the connections for the reports in the workbook. To update the connections for Exploration Views or Quick Reports in
an open workbook, use the Update connection utility. For more information, see “Utilities” on page 25.
About this task

When running this command, the name of the data source or package remains the same. You can use this command to
change only one server, such as a test server to another server, such as a production server. You choose the URLs from
the list of systems that you enter in the IBM connections section of the Options dialog box.
Procedure
1. Open the file you want to update.
2. On the IBM Planning Analytics tab, click Options .
The Options dialog box is displayed.
4. Select the system you want to update and click Edit.
5. Select the Datasource type.
6. Type the new Connection URL in the field.
7. Update the Friendly name field as required.
8. Test the connection and click save.
9. Click OK.
Results
The open IBM enabled files are searched and the server information is updated.

Set up forms-based user authentication
Forms-based authentication is not supported for connections to IBM Planning Analytics servers, it is only supported for
connections to IBM Cognos Analytics servers.
If your company uses Web-based access management software, such as SiteMinder, to provide single signon in your
security infrastructure, you must enable forms-based authentication. The forms-based authentication service allows
you to enter your credentials, such as your user name and password, through a form on a Web page. If the credentials
are valid, you are logged on to the site. The credentials persist until you explicitly log off.
Procedure

3. Under Authentication, select the Enable forms based authentication check box.
4. Click OK.
Logging
A log file is an important diagnostic tool for investigating the behavior of applications. It can help you troubleshoot
problems by recording information about the environment, exceptions, and entry and exit functions.
You can specify whether information is logged and at what level of detail. By default, log activities are saved to the
user_root_directory.
Enable logging if you are attempting to troubleshoot unexpected behavior. In this situation, the support staff will want a
copy of the entries in the log file.
Writing to log files may result in performance degradation.
Procedure

3. Under Logging, select the Log level.
• To turn logging off completely, click None.
• To record only critical issues and events in the log, click Critical.
• To record errors as well as critical issues and events, click Error.
• To record warnings as well as errors and critical issues and events, click Warning.
• To record information as well as warnings, errors, and critical issues and events, click Information.
• To record all events and issues, even routine items, click All.
4. Click OK.
The log file is created in %APPDATA%\Local\Cognos\Office Connection\Logs.
The naming format for log files is yymmdd_hhmmss.txt.
Results
The next time that you start the application, activities and information about the environment are logged in the file.
From the Options dialog box, click the View logs button to open the folder that contains the log files.
Cache management
You can reduce the file size of a workbook by clearing the cache.
About this task

For each workbook that you open or create during or after logging on, a cache worksheet is created. This worksheet
holds information about the data that needs to be rendered. You can clear the cache of packages used in workbooks
that use Planning Analytics for Microsoft Excel. Clearing the package cache reduces the size of the workbooks by

deleting unused data and metadata associated with formulas. The Clear Cache button works for all the data sources
and packages defined in Planning Analytics for Microsoft Excel. After you clear the cache, you must save workbooks to
see a reduction in file size.
Clear the cache when workbook size matters or when it is not necessary to store report results for faster processing
times. If the size of your workbook is too large due to extensive data, the clear cache function reduces the size of the
workbook. However, there is a trade-off: the processing time for populating the workbook with data increases because
the data must be retrieved from the IBM TM1 server instead of relying on the data that is saved in the cache.
Alternatively, you can specify to clear the local cache of retrieved data each time that you save the workbook or save
the workbook with a new file name. You can do this by selecting the Clear cache on save check box.
You can also automate the process for clearing the cache. For more information, see “ClearCache” on page 129.
Procedure
1. Start Planning Analytics for Microsoft Excel.
2. Open a workbook.
3. From the IBM Planning Analytics tab, click Options and then click IBM.
4. Under Cache Management, choose how you want to clear the cache:
• To clear the local cache for the active workbook, click Clear Cache.
The cache is cleared and the size of the workbook is reduced. You can now open and save additional workbooks.
To avoid creating a cache worksheet for non-IBM TM1 workbooks, you must exit Microsoft Excel.
• To clear the local cache each time that you save a workbook, or save a workbook with a new file name, select the
Clear cache on save check box.
Note: Data displayed in the workbook is cleared only when using the Clear All Data button on the IBM
Planning Analytics tab.
5. Click OK, and then save the workbook.
Utilities
The Update connection utility updates the connections for Exploration Views or Quick Reports in an open workbook.
Procedure
1. Open the file containing the reports that you want to update.
The Options dialog box is displayed.
4. Scroll to the Utilities section and click Update connection utility.
5. Select the connection that you want to upgrade from in Old connection.
6. Select the new connection and click OK.
7. Choose whether you want to refresh the data in the report. If you select Yes, then determine whether you want to
refresh just the data, or the data and report formatting.
8. After you have made your selection, you are prompted to log onto the server on the new connection.
IBM Planning Analytics settings
Application settings
Set options 25
Load recently used data source or package
If you usually work with the same data source or package, you can automatically load the most recently used data
source or package when you start IBM Planning Analytics for Microsoft Excel.
About this task

This is most useful when you use the data source or package regularly and you want an easy way to access it so that
you can quickly begin or resume work.
If the most recently used data source or package is inaccessible or missing, no source tree is shown. Select another
package to replace the missing one.
Procedure

3. Under Application settings, select the Load most recently used system and package check box.
4. Click OK.
Results
Member display count limit

You can limit the number of members shown in the source tree, drop zone, search result.
About this task

The number of members is reflected in the source tree, in each box in the Rows, Columns, and Context areas of your
exploration, and in the results of a search. This setting also limits the number of items that you can select and place in
any of the drop zones, as well as the number of results from a search.
Procedure

3. If you want to limit the number of members shown in the source tree and in the search result dialog box, under
Application settings, in the Member display count limit box, type the maximum number of members that can
appear in the source tree before showing the More or Search option.
4. Click OK.
Results

Member display count limit: 50
Member display count limit: 3
Default expand direction

You can set the default expand direction when you double click in an Exploration View or list.
About this task

Using this option, you can define which direction your Exploration View or list expands when double clicked. You can
set the default to expand either above or below.
Note: This option will only apply to new explorations created using dimensions after the option is enabled. This option
will not apply to explorations which have already been created.
You can set your Exploration View or list to expand in the following directions when double clicked:
Expand Above
Double-clicking a consolidated member expands the children above their parent.
Set options 27
Expand Below
Double-clicking a consolidated member expands the children below their parent.

Procedure

3. Under Application settings, use the drop down below Default expand direction to select the default expand
direction.
4. Click OK.
Hide commit confirmation

Disable the confirmation prompt which appears before a commit is performed.
About this task

Committing a change in a worksheet will result in a confirmation prompt which appears before the commit is
performed. This option will disable the confirmation prompt.
Procedure
Set options 29
3. Under Application settings, select the Hide commit confirmation check box.
4. Click OK.
Results
Unselected
Auto spread consolidated inputs

You can automatically convert values entered in consolidated cells into proportional spread operations.
About this task

If you enable the Auto spread consolidated input option, values entered in consolidated cells will automatically be
converted into proportional spread options.
Procedure

3. Under Application settings, select the Auto spread consolidated input check box.
4. Click OK.
Exploration or list settings
Show system and package information in exploration and list sheet

Enabling this option will display the system and package information in your Exploration Views and list views.
About this task

You can choose to display the system and package information in your Exploration Views and list views by enabling this
option.
Note: This option only applies to Exploration Views and list views created after the option is enabled. This option will
not have an effect on explorations already opened.

Procedure

3. Under Exploration or list settings, select the Show system and package information in exploration and list sheet
check box.
4. Click OK.
Results
Unselected
Selected
Assign exploration or list starting cell

This option enables a prompt for a starting cell when you create a new Exploration View or list view.
About this task

You can choose to assign a starting cell when creating a new Exploration View or list view by enabling this option. After
the option is enabled, a prompt will appear for a starting cell when creating a new exploration.
Set options 31
Procedure

3. Under Exploration or list settings, select the Assign exploration or list starting cell check box.
4. Click OK.
Results
A prompt will appear for a starting cell when creating a new exploration
Preserve user formulas

This option preserves user formulas in an Exploration View, list view, or Quick Report.
About this task

You can choose to preserve user formulas in an Exploration View, list view, or Quick Report.
Note: If this option is not selected, any formulas that you add to an Exploration View, list view, or Quick Report will be
discarded when you commit data.
Procedure

3. Under Exploration or list settings, select the Preserve user formulas check box.
4. Click OK.
Hide refresh confirmation for each worksheet and workbook

Hide the confirmation dialog box whenever you refresh an Exploration View or Quick Report.

About this task
Right clicking a cell in your Exploration View or Quick Report and selecting IBM Planning Analytics will show you
options for refreshing your workbook or worksheet. If you decide to refresh your workbook or worksheet from this
menu, a confirmation dialog box will appear. Use this option to hide the confirmation dialog box whenever you refresh
your workbooks or worksheets.
Note: This option does not apply to the Refresh or Refresh All Data buttons.
Procedure

3. Under Exploration or list settings, select the Hide refresh confirmation for each workbook or worksheet check
box.
4. Click OK.
Expand with double-click

Expand consolidated members by double clicking on it.
About this task

By enabling this option, you will be able to expand a consolidated member by double clicking on it.
Procedure

3. Under Exploration or list settings, select the Expand with double-click check box.
4. Click OK.
Allow sum on context dropdown

You can select a sum of items in the context dimension drop down of the Exploration View.
About this task

You can add a Sum button to the context dimension drop down of an Exploration View. After enabling this option, you
can click on the drop down and click Sum to select the sum of the items.
Procedure

3. Under Exploration or list settings, select the Allow sum on context dropdown check box.
4. Click OK.
Prompt for uncommitted changes

Enable a confirmation prompt which appears before a refresh is performed.
About this task

Refreshing a workbook with uncommitted changes may result in the changes being lost. This option will enable a
confirmation prompt before a refresh is made. The prompt will only display if there are changes to the workbook that
are uncommitted and at risk of being lost after a refresh.
Procedure

Set options 33
3. Under Application settings, select the Prompt for uncommitted changes check box.
4. Click OK.
Context member dropdown limit

Define the number of members to display in a dimension drop down for an Exploration View.
About this task

Use this option to define the number of members to display in the dimension area drop down.
Procedure

3. Locate Context member dropdown limit under Exploration or list settings.
4. Define a number.
5. Click OK.
Data display row limit

You can limit the number of rows that are displayed in an Exploration View or list view.
About this task

If you are pulling large quantities of data while working on your Exploration Views or list views, you may find that there
is a delay. Limiting the number of rows that are displayed in your Exploration Views or list views can help mitigate this
delay.
Note:
Under the last row of your Exploration View or list view, you can double-click More or All to see the remaining rows of
data.
Procedure

3. Locate Data display row limit under Exploration or list settings.
4. Use the field to define a number.
5. Click OK.
Expand member limit

Set the maximum number of members to display when you expand a consolidated member in your Exploration View.
About this task

Define a number in this option to limit the number of members that are displayed when you expand a consolidated
member.
Procedure

3. Locate Expand member limit under Exploration or list settings.
4. Use the field to define a number.
5. Click OK.

Grouping options
Set the way in which cells are grouped when you nest dimensions.
About this task

You can nest multiple dimensions in a row or column. This option will define how the dimensions appear when nested.
Table 1: Grouping options

Option Description
Merge cells Repeating cells in the parent dimension are merged.
Repeat labels Repeating cells in the parent dimension each have labels.
Label top cell Only the top cell of the repeating cells in the parent
dimension has a label.
Procedure

3. Locate Group options under Exploration or list settings.
4. Use the drop down menu to select an option.
5. Click OK.
Custom report settings
Set TM1RebuildOption when generating new formula content

This setting enables the TM1RebuildOption variable when you generate new formula content.
About this task

The TM1RebuildOption variable causes the worksheets in a book to be rebuilt upon opening. This forces a
recalculation to happen on each sheet in the book every time you open the book. The Set TM1RebuildOption when
generating new formula content option sets the TM1RebuildOption variable when you generate new formula
content.
Procedure

3. Locate Set TM1RebuildOption when generating new formula content under Custom report settings.
4. Select the check box.
5. Click OK.
Expand with double-click (applies to package based data sources only)

Override the default double-click action in IBM Cognos Analytics formulas.
Procedure

3. Locate Expand with double-click (applies to package based data sources only) under Custom report settings.
5. Click OK.
Set options 35
Refresh data on Excel recalculation Keys (F9, Shift F9)
Use recalculation keys to refresh data.
About this task

This setting enables you to use F9 or Shift+F9 to refresh data.
Note: You need to restart Microsoft Excel after setting this option for it to take effect.
Procedure

3. Locate Refresh data on Excel recalculation Keys (F9, Shift F9) under Custom report settings.
5. Click OK.
Refresh data on writeback

Refresh data on write back.
About this task

Use this setting to define if and how you want to refresh your data on write back.
Table 2: Refresh data on write back options

Option Description
None Data does not refresh on write back.
Workbook The data refreshes in the workbook on write back.
Worksheet The data refreshes in the worksheet on write back.
Procedure

3. Locate Refresh data on writeback under Custom report settings.
4. Select an option.
5. Click OK.
Quick report settings
Double-click option
Users can define the action executed after double-clicking on the dimension or context areas of a Quick Report.
About this task

You can use this option to define the action that occurs after double-clicking on the dimension or context areas of a
Quick Report.
Table 3: Double-click options

Option Description
None No action occurs after double-click.

Table 3: Double-click options (continued)
Option Description
Replace Double-clicking a dimension or context member opens up
the set editor to allow a replacement of the dimension /
context member.
Toggle Expands and collapses consolidated members when double-
clicked on dimension areas. Launches the set editor when
double-clicked on the context area.
Procedure

3. Locate Double-click option under Quick report settings.
4. Select an option.
5. Click OK.
Use level based indents

You can enable level based indentation in yourQuick Reports.
About this task

Level based indentations allow you to easily identify parent-child relationships in rows within Quick Reports. By
enabling level based indents, child row members will be indented under the parent row member.
Procedure

3. Under Quick Report settings, select the Use level based indents check box.
4. Click OK.
Action button settings
Upgrade IBM TM1 Perspectives action buttons

Upgrading IBM TM1 Perspectives action buttons allows them to be used in IBM Planning Analytics for Microsoft Excel.
About this task

When upgrading action buttons, note the following points:
• Trust access to the VBA project object model must be granted in Microsoft Excel. See “Enable trust access to the VBA
project object model” on page 13.
• You must have a TM1 Perspectives workbook that contains one or more action buttons.
• An administrator may upgrade action buttons in public and private workbooks.
• A non-administrator may only upgrade action buttons in private workbooks.
• Once action buttons are converted for use in IBM Planning Analytics for Microsoft Excel, they will no longer work in
TM1 Perspectives. It is recommended that a backup of all TM1 Perspectives workbooks is created before upgrading
action buttons.
Procedure

Set options 37
3. Under Action Button Settings, click Upgrade Action Buttons.
4. Optional: Under Backup Excel Files, click Browse and define a backup directory. This step will create a backup of
the TM1 Perspectives workbooks.
5. Under Conversion Log, click Browse and define a log directory.
6. Click OK.
7. Using the drop down menu, select the system that contains a TM1 Perspectives workbook that needs to be
upgraded.
8. Select the server that contains a TM1 Perspectives workbook that needs to be upgraded.
9. Select a TM1 Perspectives workbook that contains the action buttons that need to be upgraded.
10.Click Upgrade.
11.Click OK.
Results
A dialog will indicate the number of files upgraded. In this instance, a file is a workbook that has had action buttons
within it upgraded for use in IBM Planning Analytics for Microsoft Excel.
Tip: By selecting the parent server or folder to upgrade, you can upgrade action buttons in multiple TM1 Perspectives
workbooks.

Chapter 5. Explore TM1 data
Exploration Views and lists

To explore IBM TM1 data by using an Exploration View or list, select an IBM Planning Analytics data source and choose
items from that data source to place in the rows and columns of the Exploration View or list.
Before you can create an Exploration View or list, the administrator must create a TM1 data source and publish it to a
location to which you have access. The administrator must also configure your access privileges.
Administrators can create data sources and assign access privileges in IBM Cognos TM1 Performance Modeler or IBM
Cognos TM1 Architect.
You can create a TM1 Exploration View from scratch or from an existing view.
Create a list
You can explore IBM TM1 data with lists.
Use list explorations to show detailed information from your database, such as customer lists or product lists.
A list exploration is a report that shows data in rows and columns. You can create a list, for example, to look up the
names of members in a dimension and then reference the members in another worksheet where they can be used for
setting parameters.
Related concepts
“Insert blank columns” on page 40
Insert a blank column into a list to create white space or to add cell-based calculations. You can use the new column to
insert any Microsoft Excel calculation, such as AVG, MIN, or MAX and you can reference cells both inside and outside
the list.
Related tasks
“Create a list” on page 39
“Insert members” on page 41
“Suppress empty cells” on page 40
“Insert Microsoft Excel calculations” on page 51
“Nest rows or columns” on page 44
“Rename and reorder columns” on page 40
“Change the system and data source used by an exploration” on page 51
You can change the IBM Cognos system that is used by an exploration. You can also change the data source that is
used by an exploration.
Create a list
When you create list, you begin with a blank list and then drag items from the Task Pane onto the list.
Before you begin

You have access to an IBM Planning Analytics data source. The administrator has configured your access privileges.
Procedure
1. Log on to a TM1 system and select a data source.
For more information, see “Open a data source ” on page 16.
The source tree in the Task Pane displays the cube and related items of the data source, such as views.
2. On the IBM Planning Analytics tab, click List.

3. Add members to the list.
Drag dimensions, sets, or members from the Task Pane to the Columns drop zone.
Insert blank columns

Insert a blank column into a list to create white space or to add cell-based calculations. You can use the new column to
insert any Microsoft Excel calculation, such as AVG, MIN, or MAX and you can reference cells both inside and outside
the list.
Right-click a column header in the list where you want to insert a column, and click IBM Planning Analytics > Insert
user row/column.
A blank column is added next to the selected column.
Suppress empty cells

Sparse data can result in lists showing empty cells. To remove sparse data in a list, you can suppress empty cells that
contain a null or zero value.
Procedure
1. On the IBM Planning Analytics tab, click Suppression type.

2. Click Suppress Rows Only.
Results
Suppressed items are hidden.
Note: To remove suppression, repeat step 1 and click No Suppression.
Rename and reorder columns

You can reorder columns in a TM1 list. You cannot rename a column.
Procedure
1. In the Overview area, click the arrow next to the column you want to reorder, and select Reorder / Rename .
The Reorder / Rename dialog box is displayed.
2. To reorder columns, click a column name and use the arrow buttons to move the column.
3. Click OK.
Create an Exploration View

You can explore IBM TM1 data with Exploration Views.
Use Exploration Views to quickly change how you view performance measures, such as revenue or budgeted
production costs.
You can compare and manipulate data so that you can better understand relationships between data and the relative
importance of individual data items. Whether you want to assess revenue growth or to identify top performers, IBM
Planning Analytics for Microsoft Excel provides the filtering and sorting support you need for exploration and write
back.
If you are already comfortable with exploration fundamentals, you may want to refine your Exploration View by using
tasks such as manipulating the rows and columns, adding calculations, and sharing the results. For more information,
see “Nest rows or columns” on page 44, “Add calculated rows and columns” on page 44, and “Publish a workbook
to a TM1 Server Application Folder” on page 21. You can also edit data in Exploration Views. For more information, see
“Edit data” on page 48.
Create an Exploration View

Create an Exploration View by using a view
You can create an Exploration View from a view. Views are listed in the source tree in the Views folder.
This video demonstrates how to create an Exploration View by using a view.

https://youtu.be/wxygOSANrYw
Before you begin

You have access to an IBM Planning Analytics data source. The data source includes views. The administrator has
configured your access privileges.
Procedure
The source tree in the task pane displays the cube and related items of the data source, such as views.
2. Expand the Views folder.
3. Use one of the following methods to create an Exploration View.
• Drag a view onto a blank Exploration View.
• Right-click a view and click Exploration > On new sheet
• To replace an existing Exploration View, drag a view onto the Exploration View. Or, right-click a view and click
Replace Exploration.
• To convert a list to an Exploration View, drag a view onto the list.
4. Click Save to save your view. You can choose to save it as a private view, this is then available from a folder called
Private views, below the Views folder in the source tree.
Create an Exploration View from scratch
You can create an Exploration View from scratch. You can start with a blank Exploration View and drag items from the
source tree onto the Exploration View.
Before you begin

You must have access to an IBM Planning Analytics data source. The administrator has configured your access
privileges.
About this task

This video demonstrates how to create an Exploration View:
https://youtu.be/G6VOrFIBTio
Procedure
2. On the IBM Planning Analytics tab, click Exploration .

An Exploration View is created on a new worksheet.
3. Add members to the rows and columns. For more information, see “Add objects to rows, columns, and the context
area” on page 43.
Tip: You can use a view to build an Exploration View. In the source tree, expand Views and drag a view onto the
Exploration View.
4. Optionally, add members to the context area.
Insert members
You can insert members from the source tree to the rows and columns in an Exploration View that uses TM1 data. You
can also insert members to a column in a list that uses TM1 data.
Explore TM1 data 41

About this task
You can control how members are inserted by setting the insert option in the Task Pane . You can use the following
insert options.
• Insert single member, which inserts the selected member.
• Insert member with children, which inserts the selected member and its components to one level as a dynamic set.
• Insert member with descendants, which inserts an item and all levels of its component items as a dynamic set.
• Insert member with ancestors, which inserts an item along with all its related components as a dynamic set.
• Insert member with inputs, which inserts an item and its input or leaf items as a dynamic set.
You can also simultaneously insert all the members of a level “Insert all the members of a level” on page 42. In an
Exploration View, you can also insert members from different levels of the same dimension “Insert members from
multiple levels of a dimension” on page 42.
For groups of members that you use frequently, you can create a set to make selection of them easier. For more
information about sets, see “Sets for TM1” on page 64.
Procedure
1. In the Task Pane, click and select the required option.

2. In the source tree, select the members that you want to insert.
3. Drag the members to the desired location in the exploration.
To add a member to the members that already exist in an Exploration View, hold down the Ctrl key when dropping
items into the drop zones. A highlighted bar indicates where you can drop the item.
You can use Shift+click or Ctrl+click to select multiple members in a dimension and then drag them to the
exploration. When selecting multiple members, the selected members are placed in the Exploration View in the
order that you click them. To avoid rearranging members after you drag them into the Exploration View, click the
members in the order of placement that you want.
Insert members from multiple levels of a dimension
For a mixed comparison, you can position members from different levels of a dimension adjacent to each other in a
TM1 Exploration View.
About this task

You can select members from a single dimension in the source tree. You can select both contiguous and noncontiguous
members from different levels.
After you select members, you can drag the members to the Exploration View.
For groups of members that you use frequently, you can create a set to make selection of them easier. For more
information on sets, see “Sets for TM1” on page 64.
Procedure
1. In the source tree, expand the dimension to locate the members that you want to insert.
2. Use Shift+click or Ctrl+click to select multiple members in a dimension and then drag them to the Exploration View.
Tip: When selecting multiple members, the selected members are placed in the Exploration View in the order in
which you click them. To avoid rearranging members after you drag them into the Exploration View, click the
members in the order of placement that you want.
Results
The members are displayed in the Exploration View.
Insert all the members of a level
You can simultaneously insert all the members of a level into a TM1 Exploration View. Levels define the way data is
grouped in dimensions.

About this task
Use this technique to insert members at the same level from multiple consolidated members.
For example, a Region dimension might contain levels for region, country, and city. You can click a single country and
instantly insert every country in the Region dimension into the Exploration View.
Procedure
1. In the source tree, expand a single member that contains the detail that you want in the Exploration View.
2. From the Levels item, drag the level to the drop zone.
Results
The members are inserted into the Exploration View.
Note: You can also insert a level using the source tree. In the source tree, expand a dimension, expand Levels, and
then drag a level to the Exploration View.
Add objects to rows, columns, and the context area

Select the data that you want to appear in the TM1 Exploration View. You can insert dimensions, members, and
subsets.
Alternatively, you can use a view to populate the Exploration View.
Procedure
1. Create an Exploration View using an IBM Planning Analytics.
2. To use a view to populate the Exploration View, in the source tree, expand Views and drag a view onto the
Exploration View.
Or, drag a dimension, member, or set to the drop zones.
a. Drag a dimension, member, or set to the Rows drop zone.
b. Drag a dimension, member, or set to the Columns drop zone.
c. Drag dimensions, members, or sets to the context area. This step is optional. Use the context area to filter the
data in the Exploration View. For example, to filter the data by product, drag a member of the Products
dimension to the context area.
When you drag a member to a drop zone, the member and its children are inserted by default. For more information
about inserting members, see “Insert members” on page 41.
For example, to display a dimension called Retailers in the rows, click the Retailers dimension in the source tree and
drag the dimension to the Rows drop zone.
3. Save your workbook.
Results
Members are displayed in the rows and columns of the Exploration View.
Columns and rows
Rename columns or rows

You cannot rename columns or rows in a TM1 Exploration View.
Reorder columns or rows
You can move columns or rows, including calculated columns or rows, in a TM1 Exploration View.
Procedure
1. In the Overview area, click the arrow next to the row or column and click Reorder / Rename .
2. Change the order of the members using the arrows.
3. Click OK.
Explore TM1 data 43

Results
The row or column is moved in relation to the other rows or columns in the Exploration View.
Nest rows or columns
You can nest rows and columns in an Exploration View to compare information from more than one dimension in a
column or row. For example, an Exploration View shows the sales by product line for the past fiscal year. You can nest a
row to further break down the sales by order method.
You can also nest columns in a list.
In the overview area, you can drag the boxes that represent the nested items to change the nesting order.
Procedure
1. In the source tree, click the item that you want to insert. You can select a dimension, a set, or one or more members
in a dimension.
2. Drag the item to the location in the Rows or Columns drop zone that you want. Or drag the item onto the exploration
in the location that you want.
A highlight bar indicates where you can drop the item.
Insert blank columns or rows
Insert a blank column or row into an Exploration View to create white space or to add cell-based calculations. You can
use the new row or column to insert any Microsoft Excel calculation, such as AVG, MIN, or MAX.
About this task

Depending on the type of data, such as relational or asymmetric you experience very different results. Experiment with
different approaches to see what makes sense in your environment.
After you insert a row or column into an Exploration View, the rows or columns are separated into two distinct blocks of
items before and after the inserted row or column. If you want to use the Expand level / Collapse level feature, you
must do so for each block separately.
Procedure
1. Right-click a column or row header in the Exploration View where you want to insert a column or row.
If the Exploration View area expands, make sure that it does not overwrite items.
2. Click IBM Planning Analytics > Insert user row/column.
A blank column or row appears next to or under the selected column or row.
Results
The blank row or column is added to the Exploration View.
You can leave the row or column blank. You can also populate the blank column or row with a Microsoft Excel
calculation. For more information, see “Insert Microsoft Excel calculations” on page 51.
Add calculated rows and columns
Insert a calculation to make your Exploration View more meaningful by deriving additional information from the data
source. For example, you create an invoice, and you want to see the total sales amount for each product ordered.
Create a calculated column that multiplies the product price by the quantity ordered.
About this task

In addition to simple arithmetic calculations, you can perform the following calculations:
% Of
Calculates the value of a selected member as a percentage of another member, for example, fourth quarter as a
percentage of the whole year or actual as a percentage of target.
% Change
Calculates the change in value of a selected member as a percentage, for example, growth from year to year or
variance from target.

% Of Base
This calculation is available only if you select two members from different hierarchies, one on rows and the other on
columns, for example, each region's contribution (on rows) to a yearly total (on columns).
% Of Parent
This calculation is available only for TM1 data. The % of Parent calculation is available only if you select two
members from different dimensions, one on rows and the other on columns. % Of Parent calculates the value of a
selected member as a percentage of its parent, for example, January sales as a percentage of sales for the whole
year.
After you insert a calculation into an Exploration View, the rows or columns are separated into two distinct blocks of
items before or after the inserted row or column. If you want to use the Expand level / Collapse level feature, you
must do so for each block separately.
When calculations in the rows and columns of an Exploration View intersect, calculations are performed in the
following order:
• Addition or subtraction
• Multiplication or division
If both calculations have the same precedence, for example, if they are both functions, then the row calculation takes
precedence.
For information about adding Microsoft Excel calculations, see “Insert Microsoft Excel calculations” on page 51.
Procedure
1. Right-click the columns or row headers that you want to use in the calculation.
2. Click IBM Planning Analytics > Insert calculation and select the calculation that you want to perform.
Note: Calculations that are not applicable to the items you selected are grayed out.
Results
The calculated row or columns appears in the Exploration View. You can rename the calculated column or row. You can
also move the calculated column or row.
Note: To remove a calculation, right-click the calculated row or column, click IBM Planning Analytics > Hide.
Swap rows and columns
You can swap rows and columns for a different view of your data. For example, the rows contain quarters of the fiscal
year and the columns contain products. To track trends over time more easily, you can swap them so that the rows
contain products and the columns contain quarters.
Note: When you swap rows and columns in a TM1 Exploration View, sorting and top or bottom filters are removed.
Procedure
Click Swap Rows and Columns on the toolbar.

Tip: You can also use the overview area to swap individual items on rows and columns by dragging the items from one
area to the other.
Sort rows by values
Sorting rows by values makes it easier for you to organize and analyze your data.
Procedure
1. Right-click the column header cell then click IBM Planning Analytics > Sort by values.
2. Select a sort option.
Results
In the overview area, a symbol appears in the columns box to indicate a sort is applied. To remove a sort, right-click the
header cell then click IBM Planning Analytics > Sort by values > Remove.
Explore TM1 data 45

Note: When you swap rows and columns, a sort is removed.
Filter data using the context area

You can filter the data in a TM1 Exploration View using the context area. You can filter using dimensions, members, and
sets.
About this task

Changing context changes the values that appear. It does not limit or change the members in the rows or columns.
For example, you have an Exploration View showing products in the rows and months in the columns. To change the
context to Asia, you drag Asia from the source tree to the Context drop zone in the overview area. The Exploration View
then shows only the values for Asia.
You can filter using multiple values in the context area. For example, you can drag Asia and Franchise Stores to the
context area. The Exploration View then shows only the values for franchise stores in Asia.
Procedure
1. Create an Exploration View using a TM1 data source.
2. In the source tree, select one or more items to filter on.
• To filter using a dimension, select the dimension. The default member of the dimension is used for the filter.
• To filter using a set, expand the dimension, expand Subsets, and select a set. The default member of the set is
used for the filter.
• To filter using a member, expand the dimension, expand Members, and select the member.
3. Drag the item you selected to the Context drop zone.
Results
The values in the Exploration View are filtered using the items you selected.
Notice that each item has a down-arrow beside it. Click the down arrow to see options for deleting or changing the
context member. For example, if you filtered using a set, you can click the down-arrow to select a different member of
the set to use in the filter.
Limit members
You can limit the members that are displayed in a TM1 Exploration View using a variety of techniques.
You can use the following techniques.
• Use zero-suppression to hide rows or columns that contain only missing values. For more information, see “Suppress
empty cells” on page 46.
• From either rows or columns, select the members you want to show in the Exploration View, right-click the cells and
select IBM Planning Analytics > Keep.
• Use the Data Display Row Limit option to limit the number of rows displayed in the Exploration View. On the IBM
Planning Analytics tab, click Properties. In the Properties dialog box, set the number of rows to display. For
more information, see “Set properties” on page 50.
• Create a set of members. For more information, see “Sets for TM1” on page 64.
• Apply a filter to display the top or bottom values only. For more information, see “Show top or bottom results” on
page 47.
Suppress empty cells

Sparse data can result in Exploration Views showing empty cells. For example, an Exploration View that matches
employees with products, results in many rows of empty values for the revenue measure if the employee does not sell
those products. To remove sparse data in an Exploration View, you can suppress empty cells that contain a null or zero
value.
Procedure
1. On the IBM Planning Analytics tab, click Suppression type.

2. Choose where to apply the suppression:
• Suppress Rows Only
• Suppress Columns Only
• Suppress Rows and Columns
Results
Suppressed items are hidden.
Note: To remove suppression, repeat step 1 and click No Suppression.
Show top or bottom results

In an Exploration View that uses an IBM Planning Analytics data source, you can apply a filter to values to display only
the top or bottom results.
About this task

You can apply a top or bottom filter in the following ways.
• Show only the top results to quickly determine the highest values in your data. For example, you want to know which
sales representative contributed the greatest amount to yearly sales, so you apply a top percent filter.
• Show only the bottom results to quickly determine the lowest values in your data. For example, you want to know
which employees spent the fewest dollars on travel, so you apply a bottom rows filter.
Procedure
1. Right-click a column header cell then click IBM Planning Analytics > Sort by values > Top/Bottom.
2. Select a sort option and enter a value.
• For Top rows and Bottom rows, the value represents the number of rows to display.
• For Top percent and Bottom percent, the value represents a percentage of the sum of all values. For example,
you can type 10 to display the customers who contribute to the top 10% of revenue.
• For Sum of top rows and Sum of bottom rows, the value represents the sum of the results you want to display.
For example, you can type 10000000 to display the customers who contribute to the first 10 million dollars of
revenue.
Results
In the overview area, a symbol appears in the columns box to indicate a top or bottom filter is applied. To remove the
filter, right-click the header cell then click IBM Planning Analytics > Sort by values > Remove.
Note: When you swap rows and columns, a top or bottom filter is removed.
Drill down and drill up

You can drill down and drill up to change the focus of your analysis by moving between levels of information.
Drill down to see more detail. For example, you can drill down to the lowest-level member to examine the impact of a
single aspect of your business.
Drill up to compare results. For example, you can examine revenue for a single product and then drill up to see revenue
for the entire product line for comparison.
Procedure
1. To drill down or up in a single row or column, right-click a cell and then click IBM Planning Analytics > Drill Down
or IBM Planning Analytics > Drill Up.
2. To drill down or up in both a row and column simultaneously, double-click the value at the intersection of the row
and the column.
Explore TM1 data 47

Edit data
You can edit data in an Exploration View that uses an IBM Planning Analytics data source, if you have Write access to
the cells and the cells are editable.
Cell shading identifies the cells that you can edit.
• Light blue: A consolidated cell.
• Gray: A derived or locked cell. You cannot edit the value.
• White: A leaf cell.
• Dark gray: A cell with a hold applied. Place a hold on a cell to exclude it from data spreading. For more information,
see “Edit TM1 data by using data spreading” on page 73.
Planning Analytics for Microsoft Excel offers different ways to work with IBM TM1 data changes. You can determine
how your user group is designed to operate based on the options presented on the toolbar. For example, if you have
been granted Sandbox capability, you have access to the New Sandbox and Delete Sandbox options. For more
information, see “Writeback mode” on page 68 and “Sandboxes” on page 70..
To edit a value in a cell, click the cell, type the new value, and then press Enter.
To save your changes, commit the data to the TM1 Server Application Folder.
On the IBM Planning Analytics toolbar, click Commit. A confirmation dialog box is displayed.
For more information, see “Commit data in a TM1 Exploration View ” on page 78.
Cell formatting indicates the state of data changes.
• Bold blue font: The value in the cell has changed but has not been committed to the TM1 server.
• Orange background: The value in the cell has been committed to your sandbox, but has not been committed to Base.
After you commit the changes, the Exploration View displays the updated values in a normal font, indicating that you
have saved the changes.
Layouts
You can choose the most practical layout for your Exploration View.
The following layouts are available.
Basic
This layout contains one set of rows and one set of columns.
Figure 3: Example of basic sets
Nested
This layout contains sets nested either along the rows, the columns, or both.

Figure 4: Example of nested sets
Stacked
This layout contains two or more sets arranged one before another on the rows, next to each other on the columns, or
both.
Figure 5: Example of stacked sets
Asymmetric
This layout contains both nested and stacked sets. Many combinations are possible.
To create asymmetrical nesting, nest the required sets. Right-click on an open space in the rows or columns drop zone,
then click Convert axis to asymmetric. To revert the axis to a symmetric set, click the Convert axis to symmetric icon
, located above the rows or columns drop zone icon. You can then delete nested members from a parent without
deleting the nested member from all parents. For example, you can show an actual category under previous years and
show only the forecast category under the current year, because no actual is available.
Figure 6: Example of asymmetric sets
Explore TM1 data 49

Convert to other report types
You can convert Exploration Views to another report type.
For example, you can create a TM1 Exploration View, explore the data, and then convert the Exploration View to a
Custom Report to manipulate the data further using Microsoft Excel features.
• You can convert TM1 Exploration Views to Quick Reports, Dynamic Reports, and Custom Reports.
– Create a Quick Report from an Exploration View
– Create a Dynamic Report from an Exploration View
– Create a Custom Report from an Exploration View
You can also convert the data in reports from dynamic data to static data. For more information, see “Convert dynamic
data to snapshots (static data)” on page 20.
Set properties
You can set properties for an Exploration View or a list that are specific to a worksheet.
About this task

The settings in the Properties dialog box are specific to a worksheet. For information about setting global options, see
Chapter 4, “Set options,” on page 23.
In addition to changing settings, the Properties dialog box enables you to view information about the worksheet
including server and package information, and the date the worksheet was created.
Procedure
1. On the IBM Planning Analytics tab, click Properties.

2. To change the starting location of your Exploration View or list, type a new row number in the Row start box and a
new column number in the Column start box.
3. If you are working with a TM1 Exploration View, you can choose whether to process data in either CSV or raw XML
format.
• To choose CSV format for faster processing of large data sets, in the Request format drop-down box, click
Unformatted Values.
• To choose raw XML format, in the Request format drop-down box, click Formatted Values.
4. To control how labels appear in nested cells, set the Default grouping option.
Note: The Default grouping option controls how the Group / Ungroup feature works. For Exploration Views, this is
the automatic setting for presentation of metadata in nested rows and columns. For lists, this determines how the
Group /Ungroup menu items and buttons work.These settings override the settings in the Options dialog box and
affect only the current worksheet. You can leave cells ungrouped when you need to use Microsoft Excel lookup
functions or you can group cells to provide for greater readability. Changes to the Grouping option will be reflected
in the worksheet immediately, whereas changes in the Options dialog box will only be reflected when a new
Exploration View is created.
• To merge metadata into cells that span nested items and allow for full grouping, click Merge Cells.
• To repeat metadata in individual cells that span nested items, click Repeat Labels.
Use this option when you want to use other Microsoft Excel functions on the data.
• To limit cell metadata and merging to minimize labels, click Label Top Cell.
• To turn grouping off, click None.
5. To enable indenting on nested rows, set the Nested row indent property.
• To indent the nested rows, select Indented.
• To left align the nested rows, select Left Aligned.
6. To limit the number of rows displayed, set the Data Display Row Limit property.
7. After you are done setting options, click OK.

Insert Microsoft Excel calculations
You can insert any Microsoft Excel calculation, such as AVG, MIN, or MAX into an Exploration View or list. You can
reference cells both inside and outside the exploration.
Procedure
1. Insert a blank column or row.
2. Create the calculation in the first cell that applies to the inserted column or row.
You must create the formula for the calculation in the cell closest to cell A1 (the upper left most cell) of the inserted
group.
3. After you have created the calculation for a single cell, from the toolbar, click Use Server formats to remove custom
formatting.
Results
The calculation is propagated to all the inserted cells.
Tip: You can apply conditional formatting to the calculated column or row. Select the column or row. Click Home and
then click Conditional formatting. Use the conditional formatting menu to choose the styles for the cells.
Change the system and data source used by an exploration

You can change the IBM Cognos system that is used by an exploration. You can also change the data source that is
used by an exploration.
Before you begin

The information area must be displayed above the Exploration View or list to complete this task. The information area is
displayed when Show system and package information in Exploration View or list sheet in the Options dialog box is
enabled. Then click Refresh .
Procedure
1. Click the worksheet that contains the exploration.
2. In the information area above the exploration, double-click the cell that displays the System.
Or, if you want to change only the data source or package, double-click the cell that displays the Package.
3. In the Select Package dialog box, select a system.
4. Select a data source, and then click OK.
Quick Reports
You use Quick Reports to work with IBM TM1 data in Microsoft Excel in a more dynamic way.
You can combine data from multiple data sources in a Quick Report and then enhance the data by using Microsoft Excel
formulas, formats, and cell references.
Create a Quick Report

You can create a Quick Report from an Exploration View or from an existing view in the Task Pane.
This video demonstrates how to create Quick Reports.
https://youtu.be/rnF900EySKA
After you create a Quick Report, you can change or add members, format the cells, and create charts from the data. For
example, you can change members and data using options such as typing the name of a different member in a cell.
Explore TM1 data 51

You can combine multiple Quick Reports on the same worksheet. Each Quick Report can be based on a different data
source. You can provide unique perspectives by creating calculations that reference multiple Quick Reports. Another
useful option for multiple Quick Reports on the same worksheet is to use cell references to apply the same filter to
more than one Quick Report. For example, you create three Quick Reports on a worksheet to show different views of
financial performance by region. The region name appears in cell B4 in the context region on the first Quick Report. In
the second and third Quick Reports, you change the region name cell to a cell reference to cell B4. After you create the
cell references, you update the first worksheet to show data for a different region, either by dragging a different region
to cell B4 or by typing a region name in cell B4. When you refresh the data, all Quick Reports show data for the new
region.
Sets are a useful tool for building explorations and Quick Reports with TM1 data. For more information about creating
sets, including dynamic sets that can automatically reflect changes in a dimension, see “Sets for TM1” on page 64.
Quick Reports regions

Each Quick Report includes four regions: rows, columns, context, and data. Each region is a named range in Microsoft
Excel. For example, the defined name for the rows region of the first Quick Report you add to a worksheet is tm1\
\_0_R. You can use the names when you use Microsoft Excel features such as creating formulas.
To highlight a region on the worksheet, from the Task Pane, right-click a Quick Report in the Quick Reports folder and
select a region from the Show Regions list.
Create a Quick Report from an Exploration View

Create a Quick Report from an IBM TM1 Exploration View when you finish your analysis and want to present data by
using more advanced cell-based features from Microsoft Excel.
When you convert Exploration Views to Quick Reports the application places the system information, rows, and
columns in named ranges.
If you have views, explorations, or other Quick Reports available in the Task Pane, you can drag these to a worksheet to
create a Quick Report. For more information, see “Create a Quick Report by using a view” on page 52.
Procedure
1. Open or create an Exploration View.
2. Click Convert to and select an option.
For example, to create the Quick Report on a new worksheet, select Convert to > Quick Report > On New Sheet.
Results
The Exploration View is converted to a Quick Report. The Quick Report is listed in the Task Pane > Workbook tab in the
Quick Reports folder.
Note: Calculations created in an Exploration View need to be recreated in Microsoft Excel after converting to a Quick
Report.
Create a Quick Report by using a view

You use a view, Exploration View, or a Quick Report to create a new Quick Report.
A worksheet can contain more than one Quick Report.
Procedure
The source tree in the Task Pane displays the cube and related items of the data source, such as views.
3. Use one of the following methods to create a Quick Report.
• Drag a view onto a worksheet.

• Right-click a view, click Quick Report, and select where to place the Quick Report.
Note: You can also create a Quick Report by dragging an Exploration View from the Explorations folder onto a
worksheet or by dragging a Quick Report from the Quick Reports folder.
Add members
You can add members to the rows and columns of a Quick Report. You can add a member from the same dimension or
a different dimension.
This video demonstrates how to add members to Quick Reports.
https://youtu.be/7qhY8Zh7Y80
To add a row, select the cell below the last row title member, type a member name, and then click Refresh .
To add a column, select the cell to the right of the last column title member, type a member name, and then click
Refresh .
Note: If the Use Type-in Refresh option is enabled, the Quick Report refreshes automatically. You do not need to click
Refresh. To enable type-in refresh, in the Task Pane > Workbook tab, right-click the Quick Report and select
Properties > Use type-in refresh.
By default, no cell styles are applied to the added values. You can change this behavior by setting the
MapAddedRowColumnStyle parameter in the CognosOfficeReportingSettings.xml file. The possible values for
the parameter are as follows:
• NoStyle: Do not apply any cell styles to extended values
• ServerStyle: Apply server styles to extended values
• LastRowColumnStyle: Apply the styles from the last row or column to extended values
Example
Suppose that you have a Quick Report with the following members in the rows and columns:
• Columns: Total Year, Jan, and Feb in cells B7, C7, and D7
• Rows: Existing Stores Revenue, Gross Margin %, and Returns and Allowances in cells A8, A9, and A10
Table 4: Example Quick Report

Total year Jan Feb
Existing Stores Revenue 123,072,189 10,197,973 12,597,973
Gross Margin % 36.66% 34.72 34.88
Returns and Allowances 1,815,532 600,295 109,794
To add March to the Quick Report, type the member name, Mar, in cell E7, to the right of Feb.
To add Volume Discount to the Quick Report, type the member name, Volume Discount, in cell A11, below Returns and
Allowances.
Click Refresh on the Quick Report toolbar. If the Use type-in refresh option is enabled, you do not need to click
Refresh.
The Quick Report refreshes to show values for March and for Volume Discount.
Table 5: Example Quick Report with March and Volume Discount added
Total year Jan Feb Mar
Existing Stores 123,072,189 10,197,973 12,597,973 13074105
Revenue
Gross Margin % 36.66% 34.72 34.88 41.5098
Explore TM1 data 53

Table 5: Example Quick Report with March and Volume Discount added (continued)
Total year Jan Feb Mar
Returns and 1,815,532 600,295 109,794 140759.6
Allowances
Volume Discount 899712.4 74551.7 69551.7 95577.52
By default, the values in the new row and column are not formatted.
Replace members
Planning Analytics for Microsoft Excel includes several options for replacing members in a Quick Report.
About this task

To replace a member in a Quick Report, use one of the following options.
• To replace a member, drag an item from the Task Pane to a cell in the rows region, columns region, or context region.
You can replace a member with a member from the same dimension or a different dimension.
For example, the context area shows that the Quick Report is filtered on Price. You drag a different account, Units, to
the Price cell to change the context.
• To change members from the same dimension, select a cell in the rows region, columns region, or context region and
from the context menu, select IBM Planning Analytics > Replace Members. Use the Set Editor to choose members.
For example, the Quick Report shows data for the Europe region. You can use Replace Members to add the Americas
region. Europe and Americas are both part of the World dimension.
• To replace a member in the rows region, columns region, or context region, type the name of a different member in
the cell. You must type the name as it appears in the source tree. You can replace a member with a member from the
same dimension or a different dimension.
For example, the Quick Report includes a column for the S Series 2.5L Sedan model. To show data for a different
model, you type S Series 3.0L Sedan in the column heading.
Procedure
1. Replace a member in the Quick Report and press Enter.
2. Click Refresh .
Note: If Use Type-in Refresh is enabled, you do not need to click Refresh.
Refresh
If the data in your Quick Report has changed, you can refresh the data to ensure that you are working with the latest
data. You can refresh data in several ways.
About this task

You can refresh your entire workbook, a worksheet, a report, or just selected cells.
• To update the entire workbook, on the IBM Planning Analytics tab, click Refresh All Data.
You can choose to Refresh the data only or Refresh the data and report formatting.
If you choose to also refresh report formatting, formats are updated.
– Quick Reports update their formatting based on a per-Quick Report flag to use server formats (instead of the global
flag for explorations) and update formats every time the data is pulled.
• To refresh only the current worksheet, right-click any cell on the worksheet, click IBM Planning Analytics > Refresh
> Refresh worksheet.
• To refresh a specific report, follow these steps:

– In a Quick Report, click .
• To refresh only specific cells, right-click a cell or range of cells, click IBM Planning Analytics > Refresh > Refresh
selected cells.
• To refresh a Quick Report automatically when a context member changes, edit the Cognos TM1Web configuration
parameters and set the RecalcOnDataValidationChange value to true.
For information about modifying Cognos TM1Web configuration parameters see, see Modifying Cognos TM1 Web
Configuration Parameters on IBM Knowledge Center (https://www.ibm.com/support/knowledgecenter/
SSD29G_2.0.0/com.ibm.swg.ba.cognos.tm1_inst.2.0.0.doc/
c_modifyingtm1webconfigurationparameters_n50ce5.html).
• To automatically refresh values in a table when a new value is entered, enable the use type-in refresh option. You
can enable use type-in refresh in the Quick Report properties dialog box.
Note: The type-in refresh option works if an input is made directly to the meta data element. For example, if the user
has a formula in the header cell and then changes the driver, type-in refresh will not automatically update the data. In
this scenario, the user will need to do an explicit refresh to get the refreshed values based on that change.
For more information, see “Refresh data” on page 19.
Publish
You can share Quick Reports with other IBM TM1 users by publishing the workbook to a TM1 Server Application Folder.
When you open a Quick Report in IBM Planning Analytics Workspace or in TM1 Web, the Quick Report is displayed as a
live websheet. A live websheet maintains its connection to the TM1 server. If the data on the server changes, the live
websheet reflects the change. You can refresh or rebuild the Quick Report or the workbook by using the buttons on the
Websheet toolbar.
Published Quick Reports can be used as part of a sheet built in IBM Planning Analytics Workspace.
Note: In order for context members in published Quick Reports to synchronize with other dimensions in IBM Planning
Analytics Workspace, SUBNM formulas must be used in defining the context members.
For more information, see “Publish a workbook to a TM1 Server Application Folder” on page 21.
Delete
You can delete a Quick Report from a worksheet.
Procedure
1. In the Task Pane, Workbook tab, expand Quick Reports.
2. Locate the Quick Report you want to delete.
Tip: You can see where a Quick Report is located in a workbook. Right-click a Quick Report and select Show Report.
3. Right-click the Quick Report you want to delete and select Convert to snapshot.
4. Click Yes.
5. Delete the rows and columns.
Edit
You can edit data in a Quick Report, if you have Write access to the cells and the cells are editable.
If you are using server formats in the Quick Report, cell shading identifies the cells that you can edit.
• Light blue: A consolidated cell. You cannot edit the value.
• Gray: A derived or locked cell. You cannot edit the value.
• White: An editable cell.
• Dark gray: A cell with a hold applied. Place a hold on a cell to exclude it from data spreading. For more information,
see “Edit TM1 data by using data spreading” on page 73.
Planning Analytics for Microsoft Excel offers different ways to work with IBM TM1 data changes. You can determine
how your user group is designed to operate based on the options presented on the toolbar. For example, if you have
Explore TM1 data 55

been granted Sandbox capability, you have access to the New Sandbox and Delete Sandbox options. For more
information, see “Writeback mode” on page 68 and “Sandboxes” on page 70.
To edit a value in a cell, click the cell, type the new value, and then press Enter.
To save your changes, you must commit the data to the IBM TM1 server. For more information, see “Commit data in a
Quick Report” on page 79.
If you are using server formats, the cell formatting indicates the state of data changes.
• Bold blue font: The value in the cell has changed but has not been committed to the TM1 server.
• Orange background: The value in the cell has been committed to your sandbox, but has not been committed to Base.
After you commit the changes, the Quick Report displays the updated values in a normal font, indicating that you have
saved the changes.
Quick Report double-click options

Users can define the action executed after double-clicking on the dimension or context areas of a Quick Report.
About this task

You can use this option to define the action that occurs after double-clicking on the dimension or context areas of a
Quick Report.
Table 6: Drop down options

Argument Description
None No action occurs after double-clicking.
Replace Double-clicking a dimension or context member opens the set editor to

allow a replacement of that member.
Toggle Expands and collapses consolidated members when double-clicked on the

dimension areas. Launches the set editor when double-clicked on the
context area.
Procedure

3. Under Quick Report settings, select the option under the Double-click option drop down.
4. Click OK.
Change the system and data source used by a Quick Report

You can change the IBM Cognos system, TM1 server, and data source that are used by a Quick Report.
Procedure
1. Click the worksheet that contains the Quick Report.
2. In the Task Pane, Workbook tab, expand Quick Reports.
3. Right-click the Quick Report that you want to change, and click Properties.
The Properties dialog box is displayed.
4. Click Update.
The Select Package dialog box is displayed.
5. Select a Cognos system, a TM1 server, and a data source. Click OK.
The Host, TM1 Server, and Cube fields are updated.
6. Click OK.

Dynamic Reports
You can use Dynamic Reports to create complex reports that combine the functionality of IBM TM1 with Microsoft Excel
features.
Dynamic Reports are implemented through a series of worksheet functions that define the components of a form, such
as context members, row members, and display properties. When you convert an Exploration View to a Dynamic
Report, the functions are created for you.
Dynamic Reports support features available in explorations and Quick Reports, such as selectable context members,
stacked row and column dimensions, expandable/collapsible consolidations (rows only), zero suppression (rows only),
and inserting rows and columns (with some restrictions).
You can use a filter by adding the TM1RPTFILTER function, for more information, see “TM1RPTFILTER” on page 100.
In addition, you can define dynamic formatting for the Dynamic Report by using standard Microsoft Excel format
options directly in the worksheet.
Column dimensions are static in Dynamic Reports. You cannot expand or collapse consolidated column members in a
Dynamic Report by clicking them. Although the column dimension members are set when you create the Dynamic
Report, you can manually edit column members. When you enter a valid member name for a column member, the
Dynamic Report returns values from the server.
Create a Dynamic Report

You can create a Dynamic Report from a view or Exploration View that uses TM1 data.
Procedure
1. To create a Dynamic Report from an Exploration View, on the IBM Planning Analytics tab, on a worksheet that
contains an Exploration View, click Convert To > Dynamic Report and then select a location.
2. To create a Dynamic Report from a view, right-click a view in the source tree, click Dynamic Report, and select an
option.
Results
The Dynamic Report is created in a new worksheet.
Refresh, rebuild, or recreate

You can refresh, rebuild, or recreate a Dynamic Report.
About this task

When you refresh a Dynamic Report, the following actions occur:
• The data is refreshed from the TM1 server.
• The headers are updated.
• If the number of rows in the data area has changed, or if a value in the ID column of the format range has changed,
the formatting is updated.
Changes that you have made, such as drilling down or changing function parameters, are preserved. You can refresh a
cell, the worksheet, or the workbook.
When you rebuild a Dynamic Report, the following actions occur:
• The data is refreshed from the TM1 server.
• The headers are updated.
• The formatting is updated.
• The state of the rows in the Dynamic Report is updated. For example, if you change the row formula to point to a
different named set, rebuilding the Dynamic Report updates the rows. The rebuild process drops the existing row set,
reevaluates the row formula against the set, and updates the Dynamic Report rows with the result.
Explore TM1 data 57

When you recreate a Dynamic Report, the Dynamic Report is rebuilt and the rows are re-created. You need to recreate a
Dynamic Report, for example, if you change the format function of the Dynamic Report.
Procedure
1. In the source tree, Workbook tab, expand Dynamic Reports.
2. Do one of the following actions:
• To refresh the Dynamic Report, select the Dynamic Report, and then click Refresh.
• To rebuild the Dynamic Report, right-click the Dynamic Report in the tree, and then click Rebuild.
Tip: You can also rebuild all Dynamic Reports in a workbook by pressing ALT+F9.
• To recreate the Dynamic Report, right-click the Dynamic Report in the tree, and then click Repair.
Tip: You can also recreate a Dynamic Report by deleting all rows except the first row, and then rebuilding the form.
Expand and collapse rows

You can expand a consolidated member in a row to view its children.
About this task

Consolidated members that are collapsed have a plus sign (+) to the left of the member name. To expand the row to
view the child members, double-click the member name.
Consolidated members that are expanded have a minus sign (-) to the left of the member name. To collapse a
consolidated member to hide the child members, double-click the name of the consolidated member.
When you expand or collapse a member, all instances of that member are expanded or collapsed.
Suppress or display zeros

You can selectively suppress or display rows that contain only zero values in a Dynamic Report.
About this task

Zero suppression is controlled by the value of the ZeroSuppression argument to the TM1RPTVIEW function. If this
argument value is 1, zeros are suppressed in the Dynamic Report; if the argument value is 0, zeros are not suppressed
in the Dynamic Report.
Procedure
1. Unhide the rows above the Dynamic Report until you see the cell that contains the TM1RPTVIEW function.
2. To suppress zeros, change the second parameter to 1. To show zeros, change the second parameter to 0.
Edit the row set

You can use the Set Editor to modify the row set in a Dynamic Report.
About this task

The rows in a Dynamic Report are defined by a TM1RPTROW function, which is defined when the Dynamic Report is
created. When you modify the row set by using the Set Editor, the TM1RPTROW function is updated to reflect your
changes.
Procedure
1. Right-click the first (top) row member in the Dynamic Report.
2. Select IBM Planning Analytics > Edit Set.
3. Define a set by using the options available in the Set Editor. For more information, see “Sets for TM1” on page 64.
4. Click Apply and close.

Change context members
You can access a different view of cube data by changing a member in the context area.
Procedure
1. Double-click a member in the context area.
The Set Editor is displayed.
2. Select a member.
Insert columns
You can insert columns in a Dynamic Report.
You can insert a column in any of the following locations.
• Directly within the Dynamic Report
• To the right of the Dynamic Report
• To the left of the Dynamic Report
Do not insert a column between two row dimensions in a Dynamic Report.
Inserted columns persist when you refresh or rebuild (ALT+F9) the Dynamic Report.
Insert rows
You can insert rows in a worksheet that contains a Dynamic Report.
You can insert a row in any of the following locations.
• Within the Dynamic Report, outside the data area
• Above the Dynamic Report
• Below the Dynamic Report
Do not insert a row between existing rows in the data area, because this disrupts the row set of the Dynamic Report.
Inserted rows persist when you refresh or rebuild (ALT+F9) the Dynamic Report.
Display the data source or package of a formula

When working in Dynamic Reports, Custom Reports and cell-based reports, you can use more than one data source or
package. You can synchronize the source tree when moving from cells of one data source or package to another.
Synchronizing the source tree enables you to see accurately the dimensional data used to populate the cells.
Right-click a formula cell and click IBM Planning Analytics > Display Package. The Task Pane displays the package or
data source that was used to create the selected cell.
Change the server and data source used by a Dynamic Report

Update the server and data source of a Dynamic Report to switch from a test to a production environment, for example,
or to access information from a different set of financial data, such as a submission.
You need to update the formulas in the Dynamic Report to reference the new server and data source. If the formulas
reference cells to obtain the server name and data source name, update the referenced cells.
You need to modify the following formulas:
• TM1RPTVIEW
• SUBNM formulas for context members
• TM1RPTROW for the first row title member
• DBRW formulas for the cells in the data area
The first parameter of the TM1RPTVIEW formula specifies the TM1 server name and the data source name to use in the
Dynamic Report. Make the TM1RPTVIEW formula visible by unhiding the rows above the Dynamic Report until you see
the server name and data source name. Edit the TM1RPTVIEW formula to use a different server and data source.
Explore TM1 data 59

Context members are defined by SUBNM formulas. The first parameter of each SUBNM formula specifies the server
name and the data source name. Modify the SUBNM formulas to use the new server and data source.
Row title members are defined by a TM1RPTROW formula in the first row title. The second parameter of the
TM1RPTROW formula specifies the server name and the data source name. Modify the TM1RPTROW formula to use the
new server and data source.
Cells in the data area are populated by DBRW formulas. The first parameter of a DBRW formula specifies the server
name and the data source name. Modify the formulas to use the new server name and data source name. Or, if the
DBRW formulas reference a cell containing the server name and data source name, update the referenced cell.
Tip: You can modify DBRW formulas in a range of cell by using the Function Editor. For more information, see “Modify a
range of DBR and DBRW functions” on page 106.
Alternatively, return to the Exploration View that you used to create the Dynamic Report, change the server and data
source, and then convert the Exploration View to a Dynamic Report.
Report format
The formatting in a Dynamic Report is specified by format definitions within a format range. You can change the
formatting of a Dynamic Report by changing the cell formatting of format definitions and by adding new format
definitions.
The format range is hidden by default. You must reveal the format range before you can modify the default formatting
or create new format definitions. To reveal the format range, press Ctrl-A. On the Home tab, under Cells, click Format >
Hide and Unhide > Unhide Columns. Click Format > Hide and Unhide > Unhide Rows. Repeat and select Unhide
Columns. Cell A1 will now be visible. For more information about hiding and unhiding rows and columns, see the
Microsoft Excel online help.
Row 1 contains the Begin Format Range label. The last row of the format range contains the End Format Range
label. All formatting for the Dynamic Report must be defined between these labels.
The rows between the Begin Format Range label and the End Format Range label contain the default format definitions
for the Dynamic Report.
The format label column (typically column A) in the format range contains the format definition labels for each format
definition. Format definition labels can be numbers, letters, or strings.
For each data row in the Dynamic Report, the format label column (typically column A) contains a format definition
label, which determines the format definition to apply to the row. When you first generate a Dynamic Report, the format
definition corresponding to the level of each row set member is applied. Leaf indicates a leaf level member, while
Default indicates a consolidation level greater than the number of level format definitions defined in the format
range. For example, if you define format definitions for levels 0 - 5, Default defines the formatting for all other levels.
Example
For example, suppose that you have the following row set.
• World (Level 0)
– North America (Level 1)
– South America (Level 1)
- Argentina (Leaf)
- Brazil (Leaf)
- Uruguay (Leaf)
World is a level 0 member in the row set, so the 0 format definition is applied to the World row. South America is a level
1 member, so the 1 format definition is applied. Uruguay is a leaf member of the row set, so the Leaf format definition
is applied.
Format definitions
The format definitions in a Dynamic Report are applied based on the return value of an IF function in the format label
column (typically column A) for each row in the Dynamic Report.
The IF function uses several worksheet functions. The basic logic of the IF function is as follows:

1. Determine whether the row member is a consolidation.
2. If the row member is a consolidation, determine whether the subset member level of the consolidation is less than
or equal to the last level format definition defined in the format range.
• If the subset member level of the consolidation is less than or equal to the defined format definitions for levels,
return the subset member level.
• If the subset member level of the consolidation is greater than the last format definition for levels, return
Default.
3. If the row member is not a consolidation, return Leaf.
The following is an example of the default IF function that is created when you convert an Exploration View to a
Dynamic Report. The function TM1RPTELISCONSOLIDATED determines if the member is consolidated or not. The
function TM1RPTELLEV returns the level of the member. If the level is 6 or greater, the functions returns Default. If the
member is not consolidated, the function returns Leaf.
=IF(TM1RPTELISCONSOLIDATED($B$22,$B22),IF(TM1RPTELLEV($B$22,$B22)<=5,
TM1RPTELLEV($B$22,$B22),"Default"),"Leaf")
You can change the IF function. The function must return a value that can be matched to an ID in the defined format
range area. After you modify the IF function, repair the Dynamic Report to apply the formatting. For more information,
see “Apply format definitions” on page 62.
Modify formatting
You can modify the formatting of a Dynamic Report by modifying the cell formatting of format definitions.
When you modify the formatting of a cell in the format range, all cells in the Dynamic Report that use the corresponding
format definition are updated when you rebuild or repair the form. You can use the standard Microsoft Excel cell
formatting options to change format definitions.
For example, if you modify format definition 1 by applying an orange background to cell C3 and then rebuild the
Dynamic Report, all Dynamic Report rows that use format definition 1 display the orange background color in column C.
You can also modify the formatting of Dynamic Reports by modifying the named styles that are used in Dynamic
Reports. When you modify a named style, all cells in a workbook that use the named style are updated. You do not need
to refresh, rebuild, or repair the Dynamic Reports to apply the change.
For example, the named style that is applied by default to the first row of data in a Dynamic Report is AF Data 0 - IBM
Cognos. If you change the fill color of this style to green, the change is reflected in all of the cells in your workbook that
use the AF Data 0 - IBM Cognos style.
You can apply different formatting to each cell in a format definition. For example, you can apply a different background
to each cell for format definition 1. You can apply an orange background to cell C3, a blue background to cell D3, and a
green background to cell E3. When you rebuild the form, cells with format definition 1 display an orange background in
column C, a blue background in column D, and a green background in column E.
Any text or numbers you enter in a format definition row, other than in the format label column (typically column A), are
ignored. You can safely enter notes or characters to make it easy to identify the format of any cell in the format range.
For example, you can add a note in cell C3 as a reminder that this cell determines the formatting for row title members.
To modify format definitions, reveal the format range, and then apply cell formatting to the cells in the format range.
Note: To reveal the format range, unhide all rows and columns in the worksheet.
To see your changes, rebuild or repair the Dynamic Report.
Create format definitions

You can create format definitions for a Dynamic Report.
About this task

Each format definition must be assigned a unique label, and all format definitions must be inserted between the Begin
Format Range and End Format Range labels.
Explore TM1 data 61

Procedure
1. Right-click the End Format Range label and select Insert.
2. Click Entire Row and then click OK.
A new row is inserted in the format range, inheriting the formatting of the preceding row.
3. In the first column of the format range (typically column A), enter a label for the format definition.
The label must be unique within the format range.
4. Apply formatting to the cells in the new format definition row.
Tip: You can enter notes or characters in columns other than the label column (typically column A) to make it easy
to identify the format of cells in the format definition.
5. Apply the format definition to the Dynamic Report. For more information, see “Apply format definitions” on page
62.
6. Rebuild the Dynamic Report by pressing ALT+F9.
Apply format definitions

You can apply format definitions to rows in a Dynamic Report. Apply format definitions if you have changed the label of
a format definition or if you have created new format definitions.
About this task

If your Dynamic Report uses more than one format definition, the format label column (typically column A) of the first
row in the Dynamic Report must contain a function that resolves to one of the format definition labels in the format
range. The format label column is set in the TM1RPTVIEW function by using a cell reference or a named range.
To maintain dynamic formatting, do not use hardcoded values when you specify format definition labels in the format
label formula.
Procedure
1. Click the cell at the intersection of column A and the first data row in the Dynamic Report.
2. Modify the IF function to resolve to the format definition labels set in the format range.
3. Repair the Dynamic Report and view the formatting.
For more information, see “Refresh, rebuild, or recreate” on page 57.
Note: If the function in column A resolves to a value that is not used as a format definition label, no formatting is
applied to the Dynamic Report row.
Publish
You can share Dynamic Reports with other IBM TM1 users by publishing the workbook to a TM1 Server Application
Folder.
When you open a Dynamic Report in IBM Planning Analytics Workspace or in TM1 Web, the Dynamic Report is
displayed as a websheet. You can refresh or rebuild the Dynamic Report or the workbook by using the buttons on the
Websheet toolbar.
For more information, see “Publish a workbook to a TM1 Server Application Folder” on page 21.
Usage notes
Be aware of conditions and limitations when you use Dynamic Reports.
• Worksheet names must not include the dash (-) character.
Do not use a dash in the name of the worksheet that contains the Exploration View that you use to generate a
Dynamic Report. Also, do not use a dash in a worksheet that contains a Dynamic Report.
• The Sort feature of Microsoft Excel is not supported for Dynamic Reports.
• Dynamic Reports require at least one row dimension.

The Exploration View or list view from which you generate a Dynamic Report must contain at least one row
dimension. If the Exploration View or list view does not contain a row dimension, the Convert to Dynamic Report
option is disabled.
Create a Custom Report

You can create reports by using TM1 worksheet functions to populate the cells of the report.
You can create a Custom Report by using the following methods:
• Converting an Exploration View to a Custom Report
• Converting a view in the source tree to a Custom Report
• Manually entering formulas to build a report
The context members of a Custom Report can be defined by using SUBNM formulas. The data cells can be defined by
using DBRW formulas.
If you want to combine TM1 worksheet functions with automatic formatting, consider using a Dynamic Report. For
more information, see “Dynamic Reports” on page 57.
Convert a TM1 Exploration View to a Custom Report

Convert a TM1 Exploration View to a Custom Report when you want to manipulate individual cells. You can use data
from multiple data sources in a Custom Report.
You can also create a Custom Report completely from scratch using the cell-based method.
About this task

When you convert an Exploration View, you have the option of converting data on the current worksheet, copying and
moving the data to a new worksheet, or specifying the location for the converted data.
The Exploration View must have at least one row or column dimension.
In the converted report, context members are defined by SUBNM formulas. Data cells are defined by DBRW formulas.
You can modify these formulas by double-clicking the cells.
Text values in formulas are limited to 255 characters. To create text values longer than 255 characters in a formula, use
the CONCATENATE function or the concatenation operator ( & ).
Procedure
1. Go to the worksheet that contains the Exploration View that you want to convert.
2. Click Convert to > Custom Report and select an option.
• To convert the Exploration View to formulas and place the result on the current worksheet, select On This Sheet.
• To convert the Exploration View to formulas and place the result on a new worksheet, On New Sheet. By placing
the results on a new worksheet, you preserve the original Exploration View.
• To convert the Exploration View to formulas and specify the location, which is a cell in an existing spreadsheet,
select At Specified Location.
Results
The drop zones disappear. The formatting remains the same, but the cells of the Exploration View contain TM1
formulas, which link the individual cells to data in the cube. An information area above the Custom Report shows the
context members of the report.
You can continue to modify the worksheet by editing formulas and applying formatting.
Create Custom Reports by using a view

You can create a Custom Report from a view. Views are listed in the source tree in the Views folder.
Explore TM1 data 63

Before you begin
You have access to a TM1 data source. The data source includes views. The administrator has configured your access
privileges.
Procedure
1. Select a TM1 system.
2. Log on to a TM1 server.
3. Select a data source.
The source tree displays the cube and related items of the data source, such as views.
5. Right-click a view, click Custom Report and choose an option.
What to do next
You can also create Custom Reports from a view opened in the cube viewer. See “Create a report” on page 115.
Create Custom Report manually

You can create a Custom Report by entering formulas in cells and by dragging members from the source tree.
For example, you can drag members from the source tree for the rows and columns, and then use DBRW formulas to
get data from the cube. You can define context members by using SUBNM formulas, and then reference the SUBNM
cells in the DBRW formulas.
You can also copy formulas from other worksheets to build the report. For example, if the context members you need
are defined on another worksheet, you can copy the cells to the formula-based report, modify the context members as
needed, and reference them in the DBRW formulas.
Sets for TM1

Use sets to select, group, and save lists of members that identify the data you want to analyze.
Use sets when you work with IBM Planning Analytics data sources.
A dimension can have thousands of members. It is unlikely, however, that any report requires all members from all
dimensions. Use sets to narrow the list of members that you see in a report. For example, you can use sets to focus on
the following:
• Product groups that you track.
• Top-producing salespeople.
• Lagging sales regions.
• Stores that have common attributes, such as square footage and the number of employees.
You create sets using the set editor. You can then save the set to either a public or a private folder. Public sets are
available to other users. Private sets are available only to you. When you use a private set in a report, the only save
option for the report is private view.
A set is either static or dynamic.
• Static set - Contains a user-defined list of members that does not change unless you manually edit the set.
For example, you are responsible for budget planning for departments 405, 410, and 415. You create a set based on
the Department dimension that includes the members 405, 410, and 415. If your responsibilities change and you
need to add department 210, you must manually edit the set to include the 210 member of the Department
dimension.
• Dynamic set - Uses filters to determine the members to include in the set.
For example, your company sells golf equipment that includes a product line called Course Pro. You create a set
based on the Golf Equipment dimension using a filter where Name contains Course Pro. When a new product is
introduced in the Course Pro line, the new product is automatically included in reports that use the set.

Create sets
You can create sets from the members in an Exploration View or list view.
This video demonstrates how to create sets.
https://youtu.be/WO-_NWo2CVo
Procedure
1. Open the Exploration View or list view.
2. In the Overview area, click the arrow in Rows, Columns, or Context and then click Edit Set.
3. To add a member from the Available Members list to the Current Set, click the member, and then click .
If the list of Available Members is large, or you are unsure of an exact member name, or if you want to add
members that match specific criteria, you can search the list of members. You can also paste members from an
external source into the Set Editor. See Searching for members in a set and Pasting members into the set editor
4. To overwrite the Current Set to include all members in the Available Members list, click .
5. To append the members in the Available Members list to the members in the Current Set, click , and then
click .
6. To change the position of a member within the Current Set, right-click the member, then click one of the Move
options.
7. To remove a member from the Current Set, right-click the member, then click Remove.
8. To remove all members from the Current Set, click
9. To keep only selected members in the Current Set, select the members, then right-click any member, then click
Keep.
10.You can choose to display the alias for a member instead of the caption name. An alias is an alternate name for a
member. Click and select the alias that you want to display in the view.
11.You can view up to two attributes for a member. Click , select up to two attributes in the order in which you
want to view them, and then click OK.
Applying and Saving your changes
12.To apply the changes to your view without saving the new set configuration, click Apply and close.
13.To save your changes as a new set that can be reused in other views, click Save.
14.Give the new set a name.
15.Select Share public if you want to share the set with other users. Clear this option if you want the set to be yours
alone.
Search for members in a set

Use the search feature of the Edit Set window when the list of Available Members is large, or you are unsure of an exact
member name, or if you want your set to include members that match specific criteria.
This video demonstrates how to search in the set editor.
Explore TM1 data 65

https://youtu.be/OvZxBVlQl-A
When you search for members and save a set that includes the search results, a dynamic set is created which contains
a query that is run every time the set is opened. If the parent dimension for the set contains a new member that
matches the search, the new member will be included in the set the next time the set is used and the dynamic query is
run.
Procedure
1. To search for members whose names contain a specific series of characters, enter the characters in the Search
available members box, then click .
The Available Members list shows all current members that contain the characters you searched for, as well as a
member named Search that indicates the search criteria. For example, if you search for the characters "en" in a set
of the Region dimension, you get something like this:
When you add the member Search - (Name Contains en) to your set, the set includes all current members that
contain "en". Additionally, the set will include any future dimension members that contain "en", such as Greenland
or Venezuela.
2. To search on other criteria, click .

3. Select the type of criteria you want to search for: Name, Level, or Attribute.
4. Select a search operator (Contains, =, or <>), then enter the keyword or value you want to search for.
5. If you want to add criteria, click Add filter, then specify the additional search parameters.
You can search on up to three distinct criteria.
6. Click Search.
The Available Members list shows all current members that satisfy the criteria you used, as well as a member
named Search that clearly identifies the search criteria.
Related tasks
“Convert a dynamic set to static” on page 68
You can convert a dynamic set to a static set. When you convert to a static set, the MDX expression that generated the
dynamic set is deleted and the set contains only the members that are present at the time of conversion.
Paste members into the set editor

You can paste member names from an external source into the Current Set area of the Set Editor.
About this task

You can paste both member names and aliases into the Set Editor, in any combination. When you paste an alias, the
associated member name is inserted into the Current Set, and the alias is displayed only if aliases are enabled in the
Set Editor.
You can paste only member names that already exist in the parent dimension. If you attempt to paste any names that
are not members of the parent dimension, an error message indicates that the names cannot be pasted and displays a
list of those names.

Procedure
1. Copy the member names to the clipboard (CTRL+C) from an external application such as a word processor, or email.
In a spreadsheet application, names can be aligned on a single row or column, or on a contiguous rectangular range,
but there can be no empty cells within the copied selection. Empty cells will cause an error when you paste into the
Set Editor.
In other applications, such as a word processor or email, each member names should appear on a separate line or
be on a single line separated by tabs. You can also copy member names from a table. However, there cannot be any
empty strings (a line without a member, a table cell without a member, a tab location without a member) within the
copied selection.
2. Use CTRL+V to paste the member names into the Current Set.
If you paste into an empty Current Set, the pasted names become the Current Set.
If you paste into an existing Current Set without selecting an existing member as an insertion point, the pasted
names are appended to the end of the existing Current Set.
If you select a member in an existing Current Set as an insertion point and then paste into the set:
• the pasted names are inserted immediately following the selected member, provided the selected member is a
regular dimension member (leaf or consolidation)
• if the selected member is part of a group of members returned by a dynamic query (or MDX statement), the pasted
names are inserted after the last group member
Change members in a view by using advanced features

You can use Multidimensional Expression (MDX) code to determine which members appear in a view. This feature is for
advanced users only. For information on TM1 supported MDX functions, see the IBM Cognos TM1 Reference Guide.
Procedure
1. In the Exploration View or list view, go to the Overview area, click the down arrow in Rows, Columns, or Context
and then click Edit Set.
2. Click Hierarchy view , next to Current Set.

3. Click Edit MDX.
MDX code is displayed.
4. Modify the MDX as required.
5. Click OK, and then click Apply and close to return to the Exploration View.
Example
This example takes you through the steps to find car models that constitute the top 20% of sales in a particular region,
using the SData2 server.
1. Create an Exploration view using the sample TM1 server called SData2.
2. In the task pane, navigate to SalesCube cube, and create an Exploration View from the All view onto the sheet.
3. Click the arrow next to the model tile and click Edit set.
4. Click Hierarchy view , next to Current Set.

5. Click Edit MDX and replace the existing MDX expression with this code:
TOPPERCENT(TM1FILTERBYLEVEL(DESCENDANTS({[model].[model].[Total]}) , 0),
20.000000 , [SalesCube].([actvsbud].[actvsbud].[Budget],[region].
[region].CURRENTMEMBER,
[account1].[account1].[Units],[month].[month].[Year]))
6. Click Apply and close to return to the view.
7. Drag the models tile onto the columns. The models shown will be ones whose sales are at least 20% of the total.
Explore TM1 data 67

Convert a dynamic set to static
You can convert a dynamic set to a static set. When you convert to a static set, the MDX expression that generated the
dynamic set is deleted and the set contains only the members that are present at the time of conversion.
About this task

Converting a dynamic set to a static set is useful when you have added a calculation to a dynamic set, but want to
control the positioning of the calculation in the set. When you add a calculation to a dynamic set, the position of the
calculation in the set is determined by the MDX expression and the position cannot be changed. When you convert to a
static set, you can move the calculation to any location in the set.
Procedure
1. Open the dynamic set in the Set Editor.
2. Click the Members bar, then click Convert to snapshot.
3. Click Save to save the set as static.
Modify TM1 data

You can modify data in reports that use an IBM Planning Analytics data source.
For example, when your TM1 Server Application Folder administrator distributes an enterprise-wide plan, you can use
IBM Planning Analytics for Microsoft Excel to create an exploration to review, analyze, and update the portion of the
plan that is assigned to you.
You can edit TM1 data using the following methods:
• You can edit data in the cells of Exploration Views and Quick Reports.
• You can use data spreading in Exploration Views and Quick Reports to distribute numeric values.
• You can add comments to cells
You can also write back data using TM1 worksheet functions, such as DBRW.
IBM Planning Analytics for Microsoft Excel offers different ways to work with IBM TM1 data changes. The Writeback
mode and the Sandbox settings determine how changes to the server data are managed.
Writeback mode
IBM Planning Analytics for Microsoft Excel offers different ways to work with IBM TM1 data changes. The Writeback
mode in combination with the Sandbox determines how changes to the server data are managed. Options allow the
administrator to mix and match a variety of capabilities so that every installation and every user group can work in the
way that is best for them. In IBM Planning Analytics for Microsoft Excel you can hold changes in a private workspace so
that you can decide when to write the data changes back to the server and make your changes available to others. This
private workspace is called a sandbox. When you commit the data changes that were in your private workspace to the
base data, the changed values are written to the server.
If you prefer to work directly with the base data without a private workspace, you can choose a direct writeback
method. Another option your administrator can offer is the ability to name and store data changes in a named sandbox.
When you work in a sandbox IBM Planning Analytics for Microsoft Excel uses a change in cell coloring to remind you
when your data is not yet merged with the base. Once you commit the sandbox, the cell color is restored to black. For
more information, see “Cell coloring for changed data values” on page 71.

Your administrator assigns the capabilities for each user group using the administration tools in IBM TM1. Since you
could be a member of more than one group, your workspace options can be different depending on your login, the
client you use, and the combination of settings. Only administrators have access to the Capability Assignments.
Ask your administrator for details about how your system is designed to operate. To learn how to determine your
writeback mode and sandbox setting using the toolbar, see “Toolbar options” on page 70. For details about Capability
Assignments, see the IBM Cognos TM1 Operation Guide.
Writeback mode settings

The Personal Workspace Writeback Mode capability determines how data is written back to the server. Writeback mode
is determined by whether a user has the Personal Workspace Writeback Mode capability on or off.
To have the sandbox capability in IBM Planning Analytics for Microsoft Excel, an administrator must assign you rights in
IBM TM1.
Table 7: Personal workspace writeback mode capabilities
Description Capability
Changes are made directly to the base. Off

Changes are held in a temporary area and are manually written to the base using the Commit On
button or option. Cell coloring changes when data is changed but not yet committed.
The Sandbox capability determines if you can name sandboxes or if you have one default sandbox:
Table 8: Sandbox capabilities
Description Capability
You can name the sandbox and manage multiple sandboxes. On

Only one default sandbox is available. Off
The combination of these settings determines how your data changes are stored and processed.
For example, your user group might offer direct writeback with named sandboxes. This is the default work design used
by TM1. It means that you do not have a personal workspace (instead you have direct writeback to the server), but you
also have the option of naming a set of changes and manually submitting them. With this setting, when you first open a
view, you are in the base and any changes you make are written directly to the base. But, if you decide to save your
changes in a named sandbox, you can use the Commit button when you are ready to manually send those changes to
update the base.
Consider the case where you usually want to send the data directly to the server. Then you have a set of changes that
you want to gather in a group before you update the server. You can use the Create Sandbox options to save the current
data changes in a private sandbox called Best Case. When you are in the Best Case sandbox, you use the Commit
button to send the changes to the base and make the changes available to others. After Best Case is committed, those
changes merge with the base so that others can see the changes and you are now in the newly updated base.
If you are working in a sandbox, it is important to remember that you must manually commit the sandbox for others to
see your changes. Be sure that you are ready to make those changes public and that those changes should be merged
into the base.
If you move back to the base, you are back to using direct writeback. This setting offers flexibility. Users with this
setting need to remember when they are updating the base and when the Commit button is needed to make changes
available to others.
Your administrator may decide that you would like the flexibility to work in a personal workspace writeback mode, but
you do not want the complexity of creating named sandboxes. In this case, your administrator can grant you the
Personal Workspace Writeback Mode capability but deny the Sandbox capability.
Explore TM1 data 69

Toolbar options
You can determine how your user group is designed to operate based on the options presented on the toolbar. For
example, if you have been granted Sandbox capability, you have access to the Sandbox part of the toolbar. When you
do not see a sandbox list, work with data in Microsoft Excel and then commit changes directly to the IBM TM1 server.
Direct writeback and named sandboxes

By default, IBM TM1 is set to use a direct writeback with named sandboxes. Your administrator might have set your
work options to something different.
Table 9: Personal workspace mode and sandbox options

You want to Personal Workspace Sandbox
Mode
Have data changes update the server immediately. Occasionally, you want to Off On
save a set of changes and name them before committing them to the server.
The New icon indicates that you can create and delete sandboxes. Until you create a sandbox, you are operating in the
base.
Direct writeback without sandboxes

In direct writeback mode you do not have access to named sandboxes. You work with data in Microsoft Excel and then
click the Commit Changed Values icon to commit changes directly to the IBM TM1 server.
To use direct writeback across the entire installation, you can set DisableSandboxing=T in the TM1 server
configuration file. When sandbox mode is disabled for a server, the Capability Assignments are ignored.
The toolbar in this case does not have any of the sandbox icons, such as New Sandbox or Merge Sandbox. You have no
access to any kind of sandbox.
Sandboxes
With the sandbox feature you can create your own personal workspace or sandbox where you can enter and store data
value changes separate from base data.
A sandbox is not a copy of the base data, but a separate overlay or layer of your own data values on top of the base
data. The distinction between base data and sandbox data is important to understand as you make changes to your
data.
• Base data is the data that all users can access. Any edits made to base data are written directly back to the database.
• Sandbox data is the data in your own personal work area where you can edit the data values as many times as you
want and keep the changed data separate from the base data. Sandboxes are private to each user and cannot be
seen by other users. Your data values are viewable to others only when you merge them back with the base data.
Sandboxes are not stored on the client. They consist of a separate and private area of the server. When you make a
change to data in the sandbox, it is as if the base model data value is temporarily blocked by the value you entered in
the sandbox. To make the base model take on the values in the sandbox, you must merge the sandbox values with the
base values. After the sandbox data values are committed, they are merged with the base so that the changed values
then update and become the base values.
Sandboxes include the following features:
• Private data changes
Sandboxes let you try out different changes to the data before making those changes public to other users and before
committing those changes to the base data.
• Cell coloring
Changes to cell values in a sandbox are identified by a change in cell content colors. The cells change color to remind
you that the change has not yet been committed to the base data. After data is committed and processing is
complete, the cell coloring turns to black again.
Cell coloring is also applied to any dependent cells, such as consolidated or rule calculated cells, that your edits
affect.

• Manual commit
When working in a sandbox, the Merge button becomes available so you can decide when to commit changes to the
base. When you commit the data, your changes become available to other users.
• Discard changed values
In a sandbox, the Discard icon becomes available and lets you reset the values that you have changed but not
committed. When you discard changed values, the values you have not committed are reset to the values in the base
data.
• Named sandboxes let you create what-if scenarios
Depending on your configuration settings, you can name multiple sandboxes, such as Best Case or Worst Case and
then compare the impact of your edits by switching between them.
Remember: Your administrator might have disabled sandboxes for your environment or changed the writeback mode
for your user group.
To work in a sandbox, you must first open a view and then either create a new sandbox or select an existing sandbox.
When working in a sandbox, the selected sandbox applies to all the other views in your current user session.
Sandbox limitations
Sandboxes are not supported in Custom Reports or Dynamic Reports. In these kinds of reports, you always work in the
base data.
Data values for leaf and consolidated cells in a sandbox

The data values for leaf and consolidated cells in a sandbox are calculated.
Leaf cell values in a sandbox are a combination of the values in the base and sandbox cells. The user-entered values in
sandbox leaf cells override the values in the base. If the values are entered over a consolidated cell, the data will be
automatically spread and immediately recalculated. Any leaf cell that has not been changed in a sandbox still shows
the base data.
Consolidated cells in a sandbox contain values that are the sum of the leaf cells displayed in the sandbox.
Reset data values in a sandbox

Resetting a sandbox clears the data values that you have changed but not committed and resets them back to the
current values in the base data.
About this task

For example, suppose you enter values in two cells and commit the changes to the server. You then enter a value in a
third cell, but do not commit the change. When you click Discard Changed Values, the values you entered in the first
two cells are unchanged, but the third cell changes back to the value in the base data.
Procedure
1. From the IBM Planning Analytics tab, click the Discard icon.
2. Click OK.
Results
The data values in the sandbox that you have changed but not committed are set to the current values in the base data.
Any cell coloring is cleared and set to black.
Cell coloring for changed data values

When you enter a new value in a sandbox, a visual indicator is applied to the cell to remind you that the new value is
different from the base values. The color of the data changes to blue after you press the Enter key. The number changes
back to black when you commit changes. Any dependent cells, such as consolidated or rule calculated cells, also
change in appearance if your edits cause them to be recalculated.
The following table summarizes the default cell coloring that is applied in Planning Analytics for Microsoft Excel when
you enter new data values in a sandbox. These color attributes can be changed.
Explore TM1 data 71

Table 10: Cell coloring attributes
Cell or font color Description
Black font and orange background Committed sandbox data that differs from the base.
Blue bold font. Newly input data.

After you type the value and press the Enter key the font turns bold and blue.
Other cells that turn blue because of this are formula cells that reference this
cell and adopt this change in color as well.
Edited cells, dependent or consolidated cells, recalculated cells
White cell background Leaf input cell
Blue cell background Consolidated input cell
Gray cell background Locked cell
Commit changed data from a sandbox to base

You can merge all of the committed data values in your sandbox to the base data. You cannot use the undo command to
undo a merge action.
When you have multiple sandboxes and commit one of them to base, the new base values are automatically applied to
all the unchanged cells in your other sandboxes. If you entered new data values in any other sandbox, those data
values remain and do not show the new values that were committed to the base data.
Procedure
1. On the toolbar, click Sandbox and select the sandbox whose data you want to merge with the base data.
2. Click Merge Sandbox with Base.
Results
• The changed data values in the current sandbox are saved to the base data.
• The cell coloring for any changed data in the current sandbox is cleared and set to black.
• The new base data values are applied to all the unchanged cells in your other sandboxes.
When you have multiple sandboxes, you can use the toolbar to create, delete and select the different sandboxes
available to you.
Edit TM1 data in reports

In a report that is based on a TM1 data source, you can edit values directly in the cells.
You can edit TM1 data using the following methods:
• You can edit data in the cells of Exploration Views and Quick Reports.
• You can use data spreading in Exploration Views and Quick Reports to distribute numeric values.
• You can add comments to cells
You can also write back data using TM1 worksheet functions, such as DBRW.
Edit data by typing values in cells

You can edit data in the cells of an Exploration View or IBM Planning Analytics for Microsoft Excel, if you have Write
access to those cells. The Exploration View interface identifies the cells that are writable by using a special cell format
that is customizable.

Procedure
1. To edit a value in a cell, click the cell and type the new value.
2. After entering a new number, press Enter or click another cell.
The new number displays in bold and blue, which indicates that there is a new value in this cell. You must commit
the data changes to the IBM TM1 server for the change that you made to persist.
3. To save the changes to the TM1 server, click Commit .
After you click Commit, you have the option to preview information about the changes that will be saved to the TM1
server. You cannot undo changes after saving to the TM1 server.
Results
After committing the changes, the report displays the updated values in a normal font, indicating that you saved the
changes.
Edit TM1 data by using data spreading

You can use data spreading to enter or edit numeric data using a predefined distribution method, called a data spread
method.
Data spreading is available when you are working with TM1 data. Your administrator must also give you capability
assignments on the TM1 server for data spreading. For more information about capability assignments, see the IBM
Cognos TM1 Operation Guide.
Use data spreading in Exploration Views and Quick Reports
You can use data spreading to enter or edit numeric data in an Exploration View or Quick Report by using a predefined
distribution method, called a data spread method. For example, you can evenly distribute a value across a range of cells
or increment all values in a range of cells by a percentage.
Procedure
1. Select a cell or range from which you want to initiate data spreading.
You can initiate spreading from a single cell or a single linear range of cells. You cannot initiate spreading from a
non-contiguous range of cells, nor can you spread data across multiple individually selected cells or ranges in a
worksheet.
2. Right-click the cell or range and click IBM Planning Analytics > Spread.
Note: If the Spread command is not available, data spreading might be restricted on the server. Ask your
administrator to check the capability assignments configured in the data model.
3. Select a data spreading method.
The methods that are available in the Spreading dialog box depend on the cells that you selected for data
spreading. For example, some methods, such as Equal Across Leaves, are applicable to consolidated cells only.
4. Select an Update action.
5. Specify the required values.
For example, if you selected the Growth % method, enter the growth percentage.
6. Click OK.
Note: You can also apply data spreading by typing data spreading syntax in a cell.
Exclude cells from data spreading
You can apply a hold to a cell, or a range of cells, to exclude cells from data spreading operations.
About this task

You can apply a hold to consolidation cells and leaf cells.
When a consolidation hold is applied, you can initiate data spreading from a single leaf cell. Based on the data
spreading value you apply to the selected leaf cell, the remaining leaf values are updated so that the consolidation
value remains unchanged.
Explore TM1 data 73

For example, you apply a hold on the consolidated cell at the intersection of S Series 1.8L Sedan and 1 Quarter. This
consolidation hold keeps the value in the cell constant at 1,000.
Figure 7: Example hold applied to a consolidation cell
If you initiate proportional data spreading from the cell at the intersection of S Series 1.8L Sedan and Mar and specify a
value of 700, the Jan and Feb leaf values are changed proportional to their existing values. Jan has a value of 120 and
Feb has a value of 180. The consolidation of the leaves remains 1,000.
Figure 8: View of unchanged consolidation value
You can apply a hold to both the consolidated cell and one or more leaf cells. Using the original values in the example,
you apply a hold to the consolidated cell and a single leaf cell, Jan. When you change Mar from 500 to 700,
proportional spreading affects only the Feb cell. The value for Feb changes to 100. The consolidation of the leaves
remains 1,000.
Procedure
Right-click a cell and click IBM Planning Analytics > Set Hold.
To apply a hold to a range of cells, you must set a hold for each cell in the range separately.
Results
The formatting of the cell changes to show a hold is applied. To change the formatting, modify the Hold Values - IBM
Cognos style.
To remove a hold, select a cell with a hold applied and click IBM Planning Analytics > Remove Hold.
Data spreading methods
IBM Planning Analytics for Microsoft Excel provides a variety of data spreading methods that you can use to distribute
numeric data to cells in an exploration. For example, you can use data spreading to evenly distribute a value across a
range of cells or to increment all values in a range of cells by a desired percentage.
The methods that are available in the Spreading dialog box depend on the cells that you select for data spreading. For
example, some methods, such as Equal Across Leaves, are applicable to consolidated cells only.
Proportional
The proportional spread method distributes a specified value among cells proportional to existing cell values.
For example, consider a view in which the values for Argentina in the months January, February, and March are 10, 30,
and 60, respectively.
The sum of these values is 100, with the value in January accounting for 10% of the sum, the value in February
accounting for 30%, and the value in March accounting for 60%.
When you proportionally spread the value 300 across these cells and select the Replace update action, the result is as
follows.
• January contains the value 30, which is 10% of 300
• February contains the value 90, which is 30% of 300

• March contains the value 180, which is 60% of 300
These values are proportionally equivalent to the cube values that existed before you apply data spreading.
Repeat
The repeat method repeats a specified value across cells in a view.
The value you enter repeats across the range of cells that you selected. When you apply the repeat spreading method
to a single consolidated cell, the value being spread is distributed proportionally to all leaves of the consolidated cell.
Repeat Across Leaves

The repeat leaves method copies a specified value to the leaves of a consolidation. When you apply this method, you
can copy the value to all leaves of the consolidation or only to those leaves that already contain non-zero values.
For example, assume that there are several leaves of Year, Argentina with values.
If you use the repeat leaves method to copy the value 400 to the leaves of Year, Argentina currently populated with
non-zero values, the value 400 is copied to all leaves that contained non-zero values.
If you initiate the repeat leaves method from a cell identified by more than one consolidated member, the specified
value is copied to all leaves associated with the cell.
Table 11: Options for the repeat leaves data-spreading method

Option Description
Populated Leaf Cells The specified value is copied only to leaf cells currently containing non-zero
values.
All Leaf Cells The specified value is copied to all leaf cells regardless of current values.
You can apply the Repeat Across Leaves method only to consolidated cells.
Straight
The straight line method populates cube cells by linear interpolation between two specified endpoints. It requires both
a start value and an end value.
For example, with the start value of 100 and the end value of 200, the option populates the intervening cells with
values at equal intervals between the two endpoints.
You can apply straight line spreading only across single rows or columns, not across rectangular ranges.
% change
The percent change method multiplies the current cell values by a specified percentage. The product of that
multiplication can then replace, be added to, or be subtracted from the existing cell values.
When you apply the percent change method and specify a % Change value of 10, the system multiplies each cell value
by 10% (or .10). If you select the Add update action, the product of multiplication is added to the existing cell values.
The result is that each cell value is increased by 10%. The percentage change is applied across the range of cells that
you selected.
Equal
The equal spread method distributes a specified value equally across the cells in a view.
For example, consider a view where a range of 12 cells is selected.
When you equally spread the value 60 to these cells and select the Add update action, the value is equally spread
across the range and added to the existing cell values. The result is that each cell value is increased by 5 (60/12=5).
Explore TM1 data 75

The value you entered spreads equally across the range of cells that you selected. When you apply the equal spread
method to a single consolidated cell, the value being spread is distributed proportionally to all leaves of the
consolidated cell.
Equal Across Leaves

The equal spread across leaves method distributes a specified value equally across all leaves of a consolidated cell.
When you apply this method, you can choose to distribute the value to all leaves of the consolidation or only to those
leaves that already contain non-zero values.
If you initiate the equal spread across leaves method from a cell identified by more than one consolidated member, the
specified value is distributed to all leaves associated with the cell.
Table 12: Options for the equal spread leaves method

Value Description
Populated Leaf Cells The specified value is copied only to leaf cells currently containing non-zero
values.
All Leaf Cells The specified value is copied to all leaf cells regardless of current values.
You can apply the Equal Across Leaves method only to consolidated cells.
Growth %
The growth % method accepts an initial value and a growth percentage. By using the initial value as a starting point,
this method sequentially increments all values in a range by the specified growth percentage.
You can apply growth % spreading across single rows or columns, not across rectangular ranges.
Clear
The clear method clears values from cells in a view. You can apply this method to either leaf cells or consolidated cells.
When you apply the clear method to a consolidated cell, all leaves of the consolidation are set to zero.
Data spreading and hold syntax
You can apply most data spreading and hold methods using a syntax that you enter directly in cells.
You must use the user interface to apply the repeat leaves and equal spread across leaves methods. You must use the
user interface to spread across a selected range of cells.
Each data spreading syntax expression consists of a method code, a data action (optional), and method parameters.
For example: s+100
The method code is s, the data action is +, and the method parameter is 100.
The method code is a one- or two-character code for a data spreading method. For example, S is the method code for
the equal spread method. For more information, see “Data spreading and hold syntax reference table” on page 77.
The data action indicates whether spread values will replace, be added to, or be subtracted from the existing cell
values.
Replace
If you do not specify an action, the existing cell values are replaced with the spread values.
Add
Plus sign (+) adds spread values to the existing cell values
Subtract
Tilde (~) subtracts spread values from the existing cell values.
The method parameters supply all parameters required to execute a given spreading method. Most methods require
only a parameter indicating the value to be spread. The required method parameters for each spreading method are
listed in “Data spreading and hold syntax reference table” on page 77.

Data spreading and hold syntax reference table
The following table describes the data spreading and hold methods that you can apply with the syntax.
Table 13: Data spreading and hold syntax
Method Code Required Method Data Action Example

Parameters (Optional) *
Proportional Spread P Value to be spread +, ~ P<>100

Proportionally spreads the
value 100 to all leaf cells, and
replaces the existing cell
values.
Equal Spread S Value to be spread +, ~ S+200

Equally spreads the value 200
to all leaf cells, and adds the
product of spreading to the
existing cell values.
Repeat R Value to be spread +, ~ R~50

Subtracts the value 50 from all
leaf cells.
Percent Change P% Percentage +, ~ P%+10

Applies a percent change of
10% to all leaf values, adds the
product to the existing cell
values, and increments all
leaves by 10%.
Straight Line SL Start Value and End +, ~ SL100:200

Value
Replaces all leaf values, with a
start value of 100 and an end
value of 200.
Growth % GR Start Value and Growth +, ~ GR300:25

Percentage
Applies a 25% growth
percentage to the starting value
of 300 and replaces all leaf
values below the point of
insertion.
Clear C N/A N/A C

Clears values from all cells.
Leaf Hold H N/A N/A H

Holds all leaf cells.
Release Leaf Hold RH N/A N/A RH

Releases all leaf holds.
Explore TM1 data 77

Table 13: Data spreading and hold syntax (continued)
Method Code Required Method Data Action Example

Parameters (Optional) *
Consolidation Hold HC N/A N/A HC

Holds all consolidated cells.
Release Consolidation RC N/A N/A RC

Hold
Releases all holds of
consolidated cells.
Release All Holds RA N/A N/A RA

Releases all holds on the cells.
* The default data action is Replace. The spreading syntax uses a tilde (~) to denote the Subtract data action, and a plus
sign (+) to denote the Add data action.
Add and view comments in cells

You can add and view comments in TM1 Exploration Views and Quick Reports.
Before you begin

In Microsoft Excel 2013, click File > Options, and then click Advanced. Under Display, select how you want comments
to be displayed in workbooks.
About this task

Use comments to indicate the significance of the cell value. For example, state why the variance between forecast
revenue and actual revenue for a product is high. You can view all comments that were added to a cell. Use the
Annotations dialog box to create, view, update, or delete comments.
Hover over a cell with a comment marker to see the comment, the user who entered the comment, and a time stamp.
Procedure
1. To work with comments, right-click a cell, click IBM Planning Analytics > Annotations.
2. Use the Annotations dialog box to add, view, update, or delete comments.
Commit data in a TM1 Exploration View

After you have entered values in an Exploration View, you can commit your changes to save the values to the TM1
server.
On the IBM Planning Analytics toolbar, click Commit . A confirmation dialog box is displayed.
Note: If you have enabled Hide commit confirmation in the Options dialog box, the confirmation dialog box is not
displayed and the values are committed to the TM1 server. If any errors are found, the Error Report dialog box is
displayed.
To preview the changes, click Preview Changes. The Commit Preview dialog box displays the data changes, along with
any errors. Click OK.
To commit the changes, click Yes. If any errors are found, the Error Report dialog box is displayed.
Note: You cannot undo changes after you have committed them to the TM1 server.
For information about resolving errors, see “Resolve errors when committing data to a TM1 server” on page 79.

Commit data in a Quick Report
After you have entered values in a Quick Report, you can commit your changes to save the values to the TM1 server.
On the Quick Report toolbar, click Commit . The Commit Changes dialog box is displayed.
Note: If you have enabled the Hide commit confirmation option, the Commit Changes dialog box is not displayed and
the values are committed to the TM1 server. If any errors are found, the Error Report dialog box is displayed.
To preview the changes, click Preview changes. The Commit Preview dialog box displays the data changes, along with
any errors. To commit valid changes, click Commit valid. If any errors are found, the Error Report dialog box is
displayed.
To commit changes without previewing them, in the Commit Changes dialog box, choose one of the following options:
• To validate and then commit only the changed data, click Commit changes.
• To commit all data in the Quick Report without validating the data first, click Commit all. If any invalid vales are
found, they are displayed. You then have the option to continue and just commit valid data, or to cancel and fix the
invalid values.
Note: You cannot undo changes after you have committed them to the TM1 server.
For information about resolving errors, see “Resolve errors when committing data to a TM1 server” on page 79.
Resolve errors when committing data to a TM1 server

When you commit data to an IBM TM1 server, the Error Report dialog box displays any errors.
For each error, the Error Report dialog box displays an error description and the intersection of members where the
error is located. When you click a row of error information, the cursor moves to the related cell, enabling you to correct
the error.
Error messages include the following:
• Consolidated: The member is a consolidated member. The cell is read-only.
• Hold: A hold has been placed on the cell. The cell is read-only.
• Incorrect Type: The value you entered does not match the data type of the member. This error occurs, for example, if
you enter text in a cell that requires a numeric value.
• Locked: The cell is locked. The cell is read-only.
• Rule Derived: The cell contains a calculated value or a value derived from other cells. The cell is read-only.
Set options for committing data

You can choose to skip the commit confirmation step when committing data. You can also choose to commit valid
intersections automatically.
You can hide the confirmation dialog box.
• If you are working with an Exploration View, click Options, and then click IBM Planning Analytics. Select the Hide
commit confirmation check box.
• If you are working with a Quick Report, in the Commit Changes dialog box, select Hide commit confirmation. When
you commit data, the Commit Changes dialog box is not displayed and valid values are sent to the TM1 server. If any
errors are found, the Error Report dialog box is displayed.
To turn confirmation back on, click Options, and then click IBM Planning Analytics. Clear the Hide commit
confirmation check box. You can also turn confirmation on or off using the CommitWithoutConfirmation setting in
the CognosOfficeReportingSettings.xml file:
<setting name="CommitWithoutConfirmation">False</setting>
You can choose to commit valid values automatically. In the Error Report dialog box, select Automatically Commit
Valid Intersections.
To turn this feature off, change the BulkUploadAutoCommitValid setting to False in the
CognosOfficeReportingSettings.xml file:
<setting name="BulkUploadAutoCommitValid">False</setting>
Explore TM1 data 79

On Windows 7, the CognosOfficeReportingSettings.xml configuration file is installed in c:\Users\
[user_name]\AppData\Local\Cognos\Office Connection.
IBM TM1 functions

You can add formulas that use IBM TM1 functions to reports. You can also convert Exploration Views that use TM1 data
to formulas. For advanced analysis, you can create reports that use formulas to populate the cells of a worksheet.
TM1 worksheet functions in IBM Planning Analytics for Microsoft Excel

You can use TM1 worksheet functions in IBM Planning Analytics for Microsoft Excel.
You can work with TM1 worksheet functions in the following ways:
• Create an Exploration View and convert it to a Dynamic Report or a Custom Report
• Open a workbook that was created from a slice in TM1 Perspectives.
• Open a workbook that was created using the Slice to Excel export option in TM1 Web Cube Viewer.
• Manually add the TM1 worksheet functions to a worksheet.
A worksheet can contain only TM1 worksheet functions, or you can add TM1 worksheet functions to a worksheet that
contains other explorations or Quick Reports.
If a worksheet function references an object on a remote server, you must prefix the object with the server name and a
colon. For example, to refer to the SalesCube cube on the SData server, use SData:SalesCube. To refer to the Region
dimension on the SData server, use SData:Region. You must be connected to the server referenced by the function to
receive accurate values in your worksheet. If you are not connected to the server, TM1 worksheet functions return
*KEY_ERR.
Note: In IBM Planning Analytics for Microsoft Excel, parameter values are case sensitive, unlike in TM1 Perspectives. If
a parameter value is not found, the function returns RECALC_0_0.
Due to a limitation with Microsoft Excel, worksheet functions can contain no more than 30 arguments. When you
construct a cube reference, one argument must be the cube name, which leaves 29 arguments for specifying the cube
dimensions.
Some TM1 worksheet function capabilities are not supported at this time. For example, you cannot access pick lists for
dimensions and writeback capability is limited.
The IBM Cognos Office Reporting TM1 add-in provides access to the TM1 worksheet functions. The add-in is enabled
by default when you install IBM Planning Analytics for Microsoft Excel.
Modify functions by using the Function Editor

You can modify the members that are used in a function by using the Function Editor. You can also modify functions
directly, but the Function Editor can be easier to use.
Before you begin

You must be connected to the data source referenced in the server:cube parameter.
Tip: To open the data source, right-click the cell and selectIBM Planning Analytics > Display Package. The source tree
displays the data source.
Procedure
1. Click a cell that contains a function and click the Microsoft Excel function button.
The Function Editor is displayed. The Arguments list shows the parameter values currently used by the function.
The Formula Result field shows the value that is currently returned by the function.
2. Modify the members that are used in the parameters by using any of the following techniques:
• To specify a value directly, type a member name into the field. For example, to change the member for the first
dimension in the cube, type a member name into the first field.
• To use a cell reference, click . Click a cell and then click OK.

• To use the set editor, right-click the dimension, select IBM Planning Analytics > Edit set. Use the set editor to
select a member, and then click Apply and close.
Note: You might need to scroll down in the Function Editor to see all of the parameters.
3. Click OK.
The function is updated in the worksheet.
Enable and configure TM1 functions
Enable the add-in required to work with TM1 worksheet functions

To work with TM1 worksheet functions in IBM Planning Analytics for Microsoft Excel, the IBM Cognos Office Reporting
TM1 add-in must be enabled. The add-in is enabled by default when you install IBM Planning Analytics for Microsoft
Excel. If the add-in is disabled, however, you can enable it.
The IBM Cognos Office Reporting TM1 add-in is installed in [installation_location]\IBM for Microsoft
Office. The file name is CognosOfficeTM1.xll.
For information about enabling add-ins, see the Microsoft Excel Help.
Before you begin

If installed, disable the IBM TM1 Perspectives add-in. The IBM TM1 Perspectives add-in and the IBM Cognos Office
Reporting TM1 add-in cannot be active at the same time.
Configuration settings for working with TM1 worksheet functions
You can configure server connection information and specify the sandbox to use when working with TM1 worksheet
functions.
If IBM Planning Analytics for Microsoft Excel does not recognize the TM1 server required by TM1 worksheet functions,
you are prompted to select the host and server. The server connection information is saved to the
CognosOfficeXLLSettings.xml file. On Windows 7, this configuration file is installed to Users\[user name]
\AppData\Local\Cognos\Office Connection.
When you create a connection to a TM1 server to support working with TM1 worksheet functions, the default
connection information does not identify a sandbox. To specify a sandbox, you must edit the connection information in
the CognosOfficeXLLSettings.xml file to change the default sandbox setting from null to the sandbox name. The
following is an example of a connection string showing the default sandbox setting.
<userSettings>
<setting name="ServerMap">{"Servers":[{"Name":"SData","RESTuri":null,
"Sandbox":null}]}
</setting>
</userSettings>
Troubleshoot TM1 worksheet functions

Use the information in this topic to help troubleshoot TM1 worksheet functions.
#NAME!
Check that the IBM Cognos Office Reporting TM1 add-in is enabled. For more information, see “Enable the add-in
required to work with TM1 worksheet functions” on page 81.
#VALUE!
The formula could not be solved. Check the syntax. Make sure that you have specified a value for all required
parameters and in the required order. Next, verify each parameter value with the objects available on the TM1
server and cube. Make sure that object names match exactly—parameter values are case-sensitive.
*KEY_ERR
Check that you are connected and logged in to the TM1 server referenced in the formula.
RECALC_0_0
A parameter value could not be found or you are not connected to the TM1 server referenced in the formula. Log in
to the TM1 server. Next, check that the parameter values used in the formula match the names on the TM1 server
and cube. Parameter values are case-sensitive.
Blank cell or 0 when a value is expected
One or more objects could not be found.
Explore TM1 data 81

Check that the objects you specified in the formula are available.
• If the formula references a dimension, verify that the dimension is available on the TM1 Server Application
Folder.
• If the formula references a member, make sure that the member exists in the dimension you specified.
• If the formula references an attribute, make sure that the attribute exists for the member you specified.
• If the function has an index argument, verify that the value you are using is in range. For example, DIMNM returns
a blank cell if the index parameter is 0 or if the index value is greater than the number of members in the
dimension.
For example, if a DBRA formula returns an empty cell, perform the following checks:
• Check that the dimension is available on the TM1 Server Application Folder.
• Check that the member exists in the dimension.
• Check that the attribute exists for the member.
• Check that the names you are using in the formula match the names on the TM1 Server Application Folder and
cube exactly.
Tip: To see the attributes of a member, right-click the member in the tree and select Search Metadata. The Name
list contains the available attributes for the member.
Supported IBM TM1 worksheet functions

IBM Planning Analytics for Microsoft Excel supports most TM1 worksheet functions.
DBR
DBR retrieves a value from a specified TM1 cube.
In IBM Planning Analytics for Microsoft Excel, the DBR function is equivalent to the DBRW function. Both functions are
optimized to reduce network traffic and improve performance on wide area networks.
When all member arguments (m1, m2, etc.) to the function are leaf members, you can use the DBR function to write
values to the specified cube, provided that you have the appropriate access privileges to the relevant cube, dimensions,
members, and/or cells.
You can modify the members used in a DBR or DBRW function using the DBR Function Editor. For more information, see
“Modify functions by using the Function Editor” on page 80.
Syntax
DBR(server:cube, m1, m2,[...mn])
server:cube The name of a TM1 Server Application Folder and the name of a cube that is available on the
server.
m1,...mn Dimension member names that define the intersection of the cube containing the value to
be retrieved.
Arguments m1 through mn are sequence-sensitive. m1 must be a member from the first
dimension of the cube, m2 must be a member from the second dimension, and so on. These
arguments can also be the names of aliases for dimension members.
Numeric member names must be enclosed in double quotation marks.
Example

In this example, the TM1 Server Application Folder name is GO_New_Stores and the cube name is Base Sales Forecast.
The function returns the value at the intersection of Americas, Department Store, Freight, Corporate Store, Budget
version 1, and Jan.
DBR("GO_New_Stores:Base Sales Forecast", "Americas", "Department Store",

"Freight", "Corporate Store", "Budget version 1", "Jan")
DBRA
DBRA retrieves the value of a specified member attribute.
The value returned can be either a string or numeric value, depending on the attribute type.
You can also use the DBRA function to write member attribute values to the server. When you enter and commit a
value, either string or numeric, in a cell containing a DBRA function, the corresponding member attribute is updated on
the server.
Syntax
DBRA(server:dimension, element, attribute)
server:dimension The name of the TM1 Server Application Folder and the name of a dimension.
element A member of the dimension.
attribute The attribute for which you want to retrieve a value. This argument must be an attribute of
the member.
Example
In this example, the TM1 Server Application Folder name is GO_New_Stores and the dimension name is Month. The
function retrieves the value of the startdate attribute for Jan.
DBRA("GO_New_Stores:Month", "Jan", "startdate")
Example
In this example, the TM1 Server Application Folder name is SData and the dimension name is Model. The function
returns the value of the Engine Size attribute of the L Series 1.6 L Sedan member.
DBRA("SData:Model", "L Series 1.6 L Sedan", "Engine Size")
DBRW
DBRW retrieves a value from a specified TM1 cube.
In IBM Planning Analytics for Microsoft Excel, the DBRW function is equivalent to the DBR function. Both functions are
optimized to reduce network traffic and improve performance on wide area networks. For more information, see “DBR”
on page 82.
Example
In this example, the TM1 server name is GO_New_Stores and the cube name is Base Sales Forecast. The function
returns the value at the intersection of Americas, Department Store, Freight, Corporate Store, Budget version 1, and
Jan.
DBRW("GO_New_Stores:Base Sales Forecast", "Americas",

"Department Store", "Freight", "Corporate Store", "Budget version 1", "Jan")
Explore TM1 data 83

DBS
DBS sends a numeric value to a TM1 cube.
This function cannot send a string to a cube. To send strings, use the DBSS function.
In IBM Planning Analytics for Microsoft Excel, the DBS function is equivalent to the DBSW function. Both functions are
optimized to reduce network traffic and improve performance on wide area networks.
Syntax
DBS(value, server:cube, m1, m2[,...mn])
value The value being sent.
server:cube The name of the TM1 server and the cube to which the value is sent.
m1, ...mn The names of members defining the intersection in the cube to which the value is sent.
dimension of the cube, m2 must be a member from the second dimension of the cube,
and so on. These arguments can also be the names of aliases for dimension members.
Example
writes the value 5342 to the intersection of Americas, Department Store, Freight, Corporate Store, Budget version 1,
and Feb.
DBS(5342,"GO_New_Stores:Base Sales Forecast","Americas",

"Department Store","Freight","Corporate Store","Budget version 1","Feb")
DBSA
DBSA sends a value to a specified member attribute.
The value sent can be either a string or numeric value, depending on the attribute type.
Syntax
DBSA(att_value, cube:dimension, element, att_name)
att_value The value you want to send. To send the value as a string, use double quotation marks.
For example "1.8" is sent as a string value while 1.8 is sent as a numeric value.
server:dimension The name of the TM1 server and a dimension name.
element A member of the dimension.
att_name The attribute to which you want to send a value. att_name must be an attribute of the
member specified by the member argument.
Example

In this example, the TM1 server name is Planning Sample. The function writes Jane Smithers to the Manager attribute
of the UK member of the business_unit dimension.
DBSA("1.8", "SData:Model", "L Series 1.8 L Sedan", "Engine Size")
Example
In this example, the TM1 server name is SData. The function writes 1.8 to the Engine Size attribute of the L Series 1.8 L
Sedan member of the Model dimension. The value, 1.8, is in double quotation marks because the Engine Size attribute
is a text attribute. If the data type of the Engine Size parameter was Numeric, the function would be:
DBSA(1.8, "SData:model", "L Series 1.8 L Sedan", "Engine Size")
DBSS
DBSS sends a string to a cube of any number of dimensions.
This function cannot send a numeric value to a cube. Use the DBS function to send numeric values.
Syntax
DBSS(string, server:cube, m1, m2,...mn)
string The string being sent.
server:cube The name of the TM1 server and the cube to which the string is sent.
m1, ...mn The names of members defining the intersection in the cube to which the string is sent.
dimension of the cube, m2 must be a member from the second dimension of the cube,
and so on. These arguments can also be the names of aliases for dimension members.
Example
In this example, the TM1 server name is GO_New_Stores and the cube name is New Store Plan. The function writes the
value Department Store to the intersection of Americas, 1 (a member in the ID number dimension), Budget version 1,
and Retailer Type.
DBSS("Department Store", "GO_New_Stores:New Store Plan",

"Americas","1","Budget version 1","Retailer Type")
DBSW
DBSW sends a numeric value to a TM1 cube.
This function cannot send a string to a cube. To send strings, use the DBSS function.
In IBM Planning Analytics for Microsoft Excel, the DBSW function is equivalent to the DBS function. Both functions are
optimized to reduce network traffic and improve performance on wide area networks. For more information, see “DBS”
on page 84.
Example
Explore TM1 data 85

writes the value 6342 to the intersection of Americas, Department Store, Freight, Corporate Store, Budget version 1,
and Feb.
DBSW(6342,"GO_New_Stores:Base Sales Forecast","Americas",

"Department Store","Freight","Corporate Store","Budget version 1","Feb")
DFRST
DFRST returns the first member of a specified dimension. The first member in a dimension is the member with an index
number of 1.
The member with an index number of 1 might not be listed first in the tree. Index numbers are assigned to members
when they are added to a dimension. For example, if members were added and then reordered, the first member listed
in the tree might not have an index of 1.
To determine the index number of a member use the “DIMIX” on page 86 function.
Syntax
DFRST(server:dimension)
Example
In this example, the TM1 server name is GO_New_Stores. The function returns the first member in the Retailers
dimension, All Retailers. The function returns All Retailers because this member has an index number of 1 in the
Retailers dimension.
DFRST("GO_New_Stores:Retailers")
DIMIX
DIMIX returns the index number of a member within a dimension.
Syntax
DIMIX(server:dimension, element)
element The name of a member within the dimension.

If the member is not a member of the dimension specified, the function returns 0.
This argument can also be the name of an alias for a dimension member.
Example
In this example, the TM1 server name is GO_New_Stores. The function returns the index number of the Tents member
in the Products dimension. If Tents has an index number of 7, for example, the function returns 7.
DIMIX("GO_New_Stores:Products","Tents")
DIMNM
DIMNM returns the member of a dimension that corresponds to the index argument.

Syntax
DIMNM(server:dimension, index, [Alias])
index A value less than or equal to the number of members in the dimension.
The functions returns a blank cell if you enter 0 or if you enter a value greater than the
number of members in the dimension.
Example
In this example, the TM1 server name is GO_New_Stores. The function returns the name of the member with an index
of 7 in the Products dimension. If the Tents member has an index number of 7, for example, the function returns Tents.
DIMNM("GO_New_Stores:Products",7)
DIMSIZ
DIMSIZ returns the number of members within a specified dimension.
Syntax
DIMSIZ(server:dimension)
Example
In this example, the TM1 server name is GO_New_Stores. The function returns the number of members in the Budget
version dimension. For example, if the Budget version dimension contains two members, the function returns 2.
DIMSIZ("GO_New_Stores:Budget version")
DNEXT
DNEXT returns the member name that follows the member specified as an argument to the function.
Syntax
DNEXT(server:dimension, element)
element The name of a member within the dimension. This argument can also be the name of an
alias for a dimension member.
Example
Explore TM1 data 87

In this example, the TM1 server name is GO_New_Stores. The function returns the name of the member after Cooking
Gear in the Products dimension.
DNEXT("GO_New_Stores:Products","Cooking Gear")
DNLEV
DNLEV returns the number of hierarchy levels in a dimension.
Syntax
DNLEV(server:dimension)
Example
This example uses the TM1 server SData and a dimension called Region. In the Region dimension, the various nations
(Level 0) add up to regions (Level 1). The regions then add up to super-regions (Level 2), which in turn add up to the
world (Level 3).
DNLEV("SData:Region")
The region dimension has four hierarchy levels (0, 1, 2, and 3). Therefore, in this example the function returns 4.
DTYPE
DTYPE returns information about the specified member. The function returns "C" if the member is a consolidated
member, "N" if the member is a numeric member, and "S" if the member is a string member.
Syntax
DTYPE(server:dimension, element)
Example
In this example, the TM1 server name is SData. The member Europe in the dimension Region is a consolidated
member, so the example returns "C".
DTYPE("SData:Region","Europe")

In this example, the TM1 server name is GO_New_Stores. If the Tents member contains numeric data, such as product
numbers, the function returns N. If the Tents member contains text, such as model names, the function returns S.
DTYPE("GO_New_Stores:Products","Tents")
ELCOMP
ELCOMP returns the name of a child of a consolidated member in a specified dimension.
Syntax
ELCOMP(server:dimension, element, index)
element The name of a consolidated member within the dimension. This argument can also be
the name of an alias for a dimension member.
If the member is not a consolidated member, the function returns 0.
index A positive value less than or equal to the total number of children in the specified
member.
If you enter a value greater than the number of children in the member or if you enter 0,
the function returns a blank cell.
Example
In this example, the TM1 server name is GO_New_Stores. The function returns the second child member under Europe.
If Europe is a consolidated member with the children Central Europe, Northern Europe, and Southern Europe, the
function returns Northern Europe.
• Europe
– Central Europe
– Northern Europe
– Southern Europe
ELCOMP("GO_New_Stores:Country and Region","Europe",2)
ELCOMPN
ELCOMPN returns the number of children of a specified member.
Syntax
ELCOMPN(server:dimension, element)
element The name of a consolidated member within the dimension. This argument can also be
If the member is not a consolidated member, the function returns 0.
Example
Explore TM1 data 89

In this example, the TM1 server name is GO_New_Stores. The function returns the number of child members under
Europe.
If Europe is a consolidated member with the children Central Europe, Northern Europe, and Southern Europe, the
function returns 3.
ELCOMPN("GO_New_Stores:Country and Region","Europe")
Canada is not a consolidated member in the Country and Region dimension, so the function returns 0.
ELCOMPN("GO_New_Stores:Country and Region","Canada")
ELISCOMP
ELISCOMP determines whether element1 is an immediate child of element2 in the specified dimension.
The function returns TRUE if element1 is an immediate child of element2, otherwise the function returns FALSE.
Syntax
ELISCOMP(server:dimension, element1, element2)
element1 The name of a member within the dimension. This argument can also be the name of an
element2 The name of a member within the dimension. This argument can also be the name of an
Example
The following examples use the GO_New_Stores TM1 server and a dimension called Products with the following
structure:
• Total Products
– Camping Equipment
- Tents
- Lanterns
– Golfing Equipment
- Putters
- Golf Accessories
ELISCOMP("GO_New_Stores:Products","Tents","Golf Equipment")
In this example, the function returns FALSE because Tents is not a child of the Golf Equipment member in the Products
dimension.
ELISCOMP("GO_New_Stores:Products","Tents","Camping Equipment")
In this example, the function returns TRUE because Tents is a child of the Camping Equipment member.

Note that the ELISCOMP function returns TRUE only for immediate children. In the above example, Tents is a child of
Camping Equipment. Further, Camping Equipment is a child of Total Products. However, because the function returns
TRUE only for immediate children, the following example returns FALSE:
ELISCOMP("GO_New_Stores:Products","Tents","Total Products")
ELISPAR
ELISPAR determines whether member1 is an immediate parent of member2 in the specified dimension.
The function returns TRUE if member1 is an immediate parent of member2, otherwise the function returns FALSE.
Syntax
ELISPAR(server:dimension, member1, member2)
member1 The name of a member within the dimension. This argument can also be the name of an
member2 The name of a member within the dimension. This argument can also be the name of an
Example
The following examples use the GO_New_Stores TM1 server and a dimension called Products with the following
structure:
• Total Products
– Camping Equipment
- Tents
- Lanterns
– Golfing Equipment
- Putters
- Golf Accessories
– Mountaineering Equipment
- Rope
ELISPAR("GO_New_Stores:Products","Mountaineering Equipment", "Tents")
In this example, the function returns FALSE because Mountaineering Equipment is not a parent member of Tents in the
Products dimension.
ELISPAR("GO_New_Stores:Products","Camping Equipment","Tents")
In this example, the function returns TRUE because Camping Equipment is a parent member of Tents in the Products
dimension.
Note that the ELISPAR function returns TRUE only for immediate parents. In the above example, Total Products is a
parent of Camping Equipment. Further, Camping Equipment is a parent of Tents. However, because Total Products is
not an immediate parent of Tents, the following example returns FALSE:
ELISPAR("GO_New_Stores:Products","Total Products","Tents")
Explore TM1 data 91

ELLEV
ELLEV returns the level of a member within a dimension.
Syntax
ELLEV(server:dimension, element)
Example
These examples use the TM1 server SData and a dimension called Region. In the Region dimension, individual nations
(Level 0) add up to regions (Level 1). The regions then add up to super-regions (Level 2), which in turn add up to the
world (Level 3).
ELLEV("SData:region","Norway")
In this example, the function returns 0 because Norway is a leaf level member of the Region dimension.
ELLEV("SData:region ","Scandinavia")
In this example, the function returns 1 because Scandinavia is a Level 1 member of the Region dimension.
ELLEV("SData:Region","Europe")
In this example, the function returns 2 because Europe is a Level 2 member of the Region dimension.
ELPAR
ELPAR returns the parent of a member in a specified dimension
Syntax
ELPAR(server:dimension, element, index)

index A positive value less than or equal to the total number of unique consolidated members
(parents) that use the member argument as a child.
Tip: You can use the ELPARN function to find out how many unique parents a member
has.
Example
The following examples use the SData TM1 server and a dimension called model with the following structure:
• L Series 2WD
– L Series 4WD
– L Series
- L Series Sedan
- L Series Wagon
• S Series 2WD
• Total
– L Series
- L Series Sedan
- L Series Wagon
– S Series
– T Series
ELPAR("SData:model","L Series 4WD",1)
In this example, the function returns L Series 2WD, the parent of L Series 4WD.
ELPAR("SData:model","L Series",2)
In this example, the function returns Total. L Series is a child of two unique parents: L Series 2WD and Total. In the
structure of the model dimension, Total appears second, so this is the member returned by the function.
ELPAR("SData:model","L Series Wagon",2)
In this example, the function returns a blank cell. L Series Wagon appears twice, but in both cases the parent is L
Series. Since L Series Wagon does not have a second unique parent, the function returns a blank cell.
ELPARN
ELPARN returns the number of unique parents of a member in a specified dimension.
Syntax
ELPARN(server:dimension, element)
Example
The following examples use the SData TM1 server and a dimension called model with the following structure:
Explore TM1 data 93

• L Series 2WD
– L Series 4WD
– L Series
- L Series Sedan
- L Series Wagon
• S Series 2WD
• Total
– L Series
- L Series Sedan
- L Series Wagon
– S Series
– T Series
ELPARN("SData:model","L Series")
In this example, the function returns 2. In the model dimension, L Series has two unique parents: L Series 2WD and
Total.
ELPARN("SData:model","L Series Wagon")
In this example, the function returns 1. In the model dimension, L Series Wagon has one unique parent, L Series.
ELSLEN
ELSLEN returns the length of a member name within a dimension, if the member name is a string.
If the member specified is not a member of the dimension specified, or is not a string member, the function returns 0.
If you use an alias in the member argument, the function returns the length of the member name corresponding to the
alias.
Syntax
ELSLEN(server:dimension, element)
element The name of a string member within the dimension. This argument can also be the name
of an alias for a dimension member.
Example
In this example, the TM1 server name is GO_New_Stores. The function returns 6. The member Europe is a string with a
length of six characters.
ELSLEN("GO_New_Stores:Country and Region","Europe")
In this example, the function returns 15. Nordeuropa is an alias of the Northern Europe member. The Northern Europe
member is a string with a length of 15 characters.
ELSLEN("GO_New_Stores:Country and Region","Nordeuropa")
ELWEIGHT
ELWEIGHT returns the weight of a child in a consolidated member.

Syntax
ELWEIGHT(server:dimension, element1, element2)
element1 The name of a consolidated member within the dimension. This argument can also be
If member1 is not a consolidated member, the function returns 0.
element2 The name of a child of the consolidated member. This argument can also be the name of
an alias for a dimension member.
If member1 is not a parent of member2, the function returns 0.
Example
The following examples use the SData TM1 server and a member called Gross Margin with two child members.
ELWEIGHT("SData:Account1","Gross Margin","Sales")
In this example, the function returns 1. The member Sales, which is a child of Gross Margin, has a weight of 1.
ELWEIGHT("SData:Account1","Gross Margin","Variable Costs")
In this example, the function returns -1. The member Variable Costs, which is a child of Gross Margin, has a weight of
-1.
SUBNM
SUBNM returns the member of a set corresponding to the IndexOrName argument.
If you include the optional alias parameter to this function, the function returns the alias for the selected member.
When you double-click a cell containing a SUBNM function and the data source that contains the SUBNM function
dimension is selected, the Set Editor opens.
When you click a cell containing a SUBNM function that references a set, a drop-down arrow is displayed. Click the
down arrow to select a different member from the set. This feature is available when you are logged on to a data source
that contains the dimension.
Syntax
SUBNM(server:dimension, set, IndexOrName, [alias])
set The name of a set of the dimension.
Explore TM1 data 95

IndexOrName An index into the set or the name of a member in the set.
If an index, a positive integer less than or equal to the total number of members in the
specified set. If a name, a string representing the name of a member of the set. You can
also use the alias of a member.
alias The name of an alias that exists for the set. This is an optional argument. If it is used, the
specified alias is applied when the Set Editor opens and the function returns the alias for
the selected member.
Example
The following examples use the GO_New_Stores TM1 server, a dimension called Country and Region, and a set called
Countries Only.
• Countries Only
– Americas
– Central Europe
– Northern Europe
– Southern Europe
– Asia-Pacific
SUBNM("GO_New_Stores:Country and Region", "Countries Only",

"Americas")
In this example, the function returns Americas.
SUBNM("GO_New_Stores:Country and Region", "Countries Only",2)
In this example, the function returns Central Europe, which is the second member in the Countries Only set of the
Country and Region dimension.
The following examples use the Planning Sample TM1 server, a dimension called plan_department, and a set called All
Departments. The members in this dimension are named with department ID numbers. The Department alias contains
the department names.
The following table lists the members in the All Departments set. The first column lists the member names. The second
column shows the Department alias of each member.
member name Department

1000 Total Organization
100 Sales
200 Marketing
300 Engineering
SUBNM("Planning Sample:plan_department","All Departments",

"300","Department")
In this example, the function returns Engineering. The third argument is the member name, 300, and the fourth
argument, Department, is the name of the alias to retrieve. The Department alias for 300 is Engineering.
SUBNM("Planning Sample:plan_department","All Departments",

"100","Department_Spanish")

Suppose another alias, Department_Spanish, contains department names in Spanish. In this example, the function
returns Ventas. The third argument is the member name, 100, and the fourth argument, Department_Spanish, is the
name of the alias to retrieve. The Department_Spanish alias for 100 is Ventas.
When you double-click the cell containing this example, the Set Editor opens. The Available Members list displays the
Spanish aliases for the plan_department dimension and its members.
SUBSIZ
SUBSIZ returns the number of members in a dimension set.
Syntax
SUBSIZ(server:dimension, set)
set The name of a set of the dimension.
Example
In this example, the TM1 server name is GO_New_Stores. The function returns the number of members in the
Countries Only set of the Country and Region dimension. If the set contains six members, for example, the function
returns 6.
SUBSIZ("GO_New_Stores:Country and Region", "Countries Only")
TABDIM
TABDIM returns the dimension name that corresponds to a given index argument.
Syntax
TABDIM(server:cube, index)
server:cube The name of the TM1 server and a cube name.
index A positive value less than or equal to the total number of dimensions in the cube.
The functions returns a blank cell if you enter 0 or if you enter a value greater than the
number of dimensions in the cube.
Example
In this example, the TM1 server name is GO_New_Stores and the cube name is Base Sales Forecast. The Base Sales
Forecast cube has the following dimensions: Country and Region, Retailers, Existing Stores Revenue, Store Type,
Budget version, and Month. The function returns Store Type, the fourth dimension in the Base Sales Forecast cube with
an index number of 4.
TABDIM("GO_New_Stores:Base Sales Forecast",4)
TM1ELLIST
TM1ELLIST returns a downwards array vector of values. It is useful because you can get a set of element values from a
TM1 model by using a single formula.
Explore TM1 data 97

Syntax
TM1ELLIST(ServerDimension, SetName, ElementList,

AliasOverride, ExpandAbove,MDXOverride, IndentRate, IndentCharacter)
ServerDimension A dimension, specified using the format server:dimension.
SetName A named set. If this argument is empty, all elements of the dimension are used.
Elementlist An array of values that specifies a list of elements to constitute a set. For example,
ElementList can reference a cell range.
When this argument is supplied, the named set specified by the SetName argument is
ignored.
If this argument is empty, the elements from the set specified by the SetName argument
are used.
AliasOverride A string that defines the alias used for the set.
When this argument is supplied, it overrides the default alias property defined by the
subset specified by the SetName argument.
If this argument is empty, the alias from the set specified by the SubsetName argument
is used.
ExpandAbove A Boolean flag to turn on or off the set Expand Above property.
When this argument is supplied, it overrides the default Expand Above property defined
by the subset specified by the Set argument. If the argument value is 1, consolidated
members expand upward when drilling. If the argument value is 0, consolidated
members expand downward when drilling.If this argument is empty, the Expand Above
property from the subset specified by the Subset argument is used.
MDXOverride An MDX statement that applies to the subset specified by the SubsetName/ElementList
argument.
When this argument is supplied, it overrides the default MDX filter defined by the subset
specified by the SetName argument.
If this argument is empty or omitted, the members from the set specified by the
SetName argument are used.
IndentRate An integer value to indicate how many indentations are applied to each level when
drilling down on a consolidated member. If the argument value is 0, no auto-indentation
is performed. IndentRate is relative to the set level of the set elements.
This is an optional argument. When the value is missing, one indentation is applied to
each level as you drill down on a consolidated member.
IndentCharacter IndentChar sets the symbol used to provide in-string indentation, the default is en-
space character (the normal space symbol).
Example
TM1ELLIST("Planning Sample:plan_business_unit")

TM1GLOBALSANDBOX
TM1GLOBALSANDBOX returns the current global active sandbox for the user.
Syntax
TM1GLOBALSANDBOX(SERVER)
Server The name of the TM1 server.
Example
TM1GLOBALSANDBOX("Planning Sample")
TM1INFO
TM1INFO returns information about the current TM1 version and client.
Syntax
TM1INFO("Property Name")
Property Name The property name can be one of the following:

clientversion
Returns the full client version number. For example, 10.2.10000
clientversionmajor
Returns the major client version number.
clientversionminor
Returns the minor client version number.
clientversionpatch
Returns fix pack and hotfix number.
client
Returns the name of the client. For example, cor or websheet.
Example
TM1USER("clientversion")
TM1PRIMARYDB
TM1PRIMARYDB returns the primary TM1 server name that the user is authenticated through, even if the user is
implicitly logged into multiple TM1 servers. For example, Planning Sample. This function doesn't contain any
arguments.
Syntax
TM1PRIMARYDB()
TM1RPTELISCONSOLIDATED
TM1RPTELISCONSOLIDATED returns a Boolean value to indicate whether a member in a Dynamic Report is
consolidated.
Explore TM1 data 99

Syntax
TM1RPTELISCONSOLIDATED(RptRowFormula, RowHeaderCell)
RptRowFormula An absolute reference to a cell that contains a TM1RPTROW formula.
RowHeaderCell A relative reference to a cell that contains a member from the TM1RPTROW formula.
Example
TM1RPTELISCONSOLIDATED($B$25,$B25)
TM1RPTELLSEXPANDED
TM1RPTELLSEXPANDED returns a Boolean value to indicate whether or not a member is expanded in a Dynamic Report
row set.
Syntax
TM1RptElIsExpanded(RptRowFormula, Member)
Example
TM1RPTELLSEXPANDED($B$25,$B25)
TM1RPTELLEV
TM1RPTELLEV returns an integer value representing a member level within a hierarchy. This function is used in
Dynamic Reports.
Note: In the current release, TM1RPTELLEV and ELLEV are equivalent. Both functions return the level of a member
based on the dimension.
Syntax
TM1RPTELLEV(RptRowFormula, Member)
Example
TM1RPTELLEV($B$25,$B25)
TM1RPTFILTER
TM1RPTFILTER defines the filter applied to a Dynamic Report column dimension.
Syntax
TM1RPTFILTER(ReportView,Tuple,FilterFunction,FilterValue,SortOrder)
ReportView A cell reference to a cell that contains a TM1RPTVIEW formula. The filter applies to the
view specified by the TM1RPTVIEW formula.
Tuple A tuple string specifying the member in the column dimension to which the filter
applies. For example, [month].[Feb].
FilterFunction One of the following filter function names:

• TOPCOUNT
• BOTTOMCOUNT
• TOPPERCENT
• BOTTOMPERCENT
• TOPSUM
• BOTTOMSUM
FilterValue A filter value.
SortOrder One of the following sort orders:

• asc: Ascending
• desc: Descending
• nbasc: Ascending without breaking the hierarchy
• nbdesc: Descending without breaking the hierarchy
Example
TM1RPTFILTER($B$4,"[month].[Jan]","TOPCOUNT",5,"asc")
TM1RPTROW
TM1RPTROW sets the Dynamic Report master row definition. The master row definition governs the behavior of all
rows in the Dynamic Report.
Syntax
TM1RPTROW(SAFID, Dimension, SetName, ElementList,

AliasOverride, ExpandAbove,MDXOverride, IndentRate, AllowDrilling)
SAFID A reference to a cell that contains a TM1RPTVIEW formula.
ServerDimension A dimension, specified using the format server:dimension.
SetName A named set. If this argument is empty, all elements of the dimension are used.
Explore TM1 data 101

ElementList An array of values that specifies a list of members to constitute a set. For example,
ElementList can reference a cell range.
When this argument is supplied, the named set specified by the SetName is ignored.
If this argument is empty, the members from the set specified by the SetName are used.
AliasOverride A string that defines the alias used for the set.
When this argument is supplied, it overrides the default alias property defined by the set
specified by the Set argument.
If this argument is empty, the alias from the set specified by the set argument is used.
ExpandAbove Note: The Expand Above feature is not implemented. Rows expand below.
MDXOverride An MDX statement that applies to the set specified by the Set/SetMembers argument.
When this argument is supplied, it overrides the default MDX filter defined by the set
specified by the set argument.
If this argument is empty or omitted, the members from the set specified by the set
argument are used.
IndentRate An integer value to indicate how many indentations are applied to each level when
drilling down on a consolidated member. If the argument value is 0, no auto-indentation
is performed.
This is an optional argument. When the value is missing, one indentation is applied to
each level as you drill down on a consolidated member.
AllowDrilling A Boolean flag to turn on or off drilling on consolidated members.

When this argument value is 1, you can drill down on consolidated members in the
Dynamic Report.
When this argument value is 0, you cannot drill down on consolidated members in the
Dynamic Report.
This is an optional argument. When the argument is missing, the default behavior is to
allow drilling on consolidated members.
Example
TM1RPTROW($B$9,"SData:region",,"$B$17:$B$18",,1,"",5, 0)
TM1RPTROW($B$16,"GO_New_Stores:Retailers",,,,,B$15)
TM1RPTTITLE
TM1RPTTITLE defines a Dynamic Report title dimension.
Syntax
TM1RPTTITLE(server:dimension,Element)
server:dimension A dimension, specified using the format server:dimension.
Element A cell reference to a cell that contains a SUBNM function that

returns a member name.
Example
TM1RPTTITLE("SData:model",$C$7)
TM1RPTVIEW
TM1RPTVIEW defines the view displayed in a Dynamic Report.
Syntax
TM1RPTVIEW(ViewID,ZeroSuppression,TM1RPTTITLE,...)
ViewID A name for the view using the format server:cube:unique_id.
ZeroSuppression A Boolean flag to turn on or off the zero suppression property for the view. 1 = on, 0 = off
TM1RPTTITLE For each title dimension in the Dynamic Report, include a reference to a TM1RPTTITLE
function as an argument to TM1RPTVIEW.
FormatRange The formatting range for the Dynamic Report. You can use a cell reference or a named
range for this parameter.
When you create a Dynamic Report, a named range called TM1RPTFMTRNG is created
to include all formatting range cells. You can use this named range as an argument.
IDColumn The column in the Dynamic Report that contains format IDs. You can use a cell reference
or a named range for this parameter.
When you create a Dynamic Report, a named range called TM1RPTFMTIDCOL is created
to include all formatting range cells. You can use this named range as an argument.
Example
TM1RPTVIEW("SData:SalesCube:6", 0, TM1RPTTITLE("SData:actvsbud",$C$6),
TM1RPTTITLE("SData:model",$C$7), TM1RPTTITLE("SData:account1",$C$8),
TM1RPTFMTRNG,TM1RPTFMTIDCOL)
TM1USER
TM1USER returns the user name of the user currently logged in to TM1 and using the TM1USER function.
If the current user is not connected to a TM1 server, or if the specified server is not running, TM1USER returns an
empty string.
Note: If you run TM1USER against a TM1 server that is configured to use Cognos security, the function returns the user
name, not the internal user name/CAMID. (In TM1 Perspectives, this function returns the internal user name/CAMID.)
Syntax
TM1USER("server")

server The name of a TM1 server.
Example
If a user named BrianT is logged in to the GO_New_Stores server, and BrianT runs the TM1USER function, this example
returns BrianT.
TM1USER("GO_New_Stores")
VIEW
VIEW is primarily used for compatibility with IBM TM1 Perspectives worksheets. For example, when you create a slice
from a TM1 Perspectives worksheet and open it in IBM Planning Analytics for Microsoft Excel, you might see a VIEW
function. The VIEW function defines a view of the cube specified by the server:cube argument.
DBR and DBRW formulas can refer to a VIEW function.
A workbook can contain multiple VIEW functions.
Syntax
VIEW(server:cube, m1,m2[,...mn])
server:cube The name of the TM1 server and the name of the cube from which to retrieve data.
m1,...mn Either specific members in the slice to be used as titles, or the string "!".
The string "!" indicates that the corresponding dimension is a row or column in the view.
dimension of the cube, m2 must be a member from the second dimension, and so on.
These arguments can also be the names of aliases for dimension members.
Example
The following examples use the GO_New_Stores TM1 server. The dimensions in this cube are:
• Retailers
• Countries_currency
• Products
• Month
• Budget version
• Store Sales Plan
VIEW("GO_New_Stores:Store Sales Plan")
In this example, the function defines a view for the Store Sales Plan cube. The cell containing the VIEW function
displays GO_New_Stores:Store Sales Plan.
VIEW("GO_New_Stores:Store Sales Plan","Department Store",

"Americas","!", "!", "Budget version 1","Quantity")
In this example, the function defines a view as follows:

• Title members: Department Store, Americas, Budget version 1, Quantity
• Rows: Products
• Columns: Month
The cell containing the VIEW function displays GO_New_Stores:Store Sales Plan.
You can also use cell references in a VIEW function:
VIEW("GO_New_Stores:Store Sales Plan",$B$20,"$B$21","!", "!",

$B$23,$B$24)
Suppose that cell B5 contains the VIEW function shown above. You can display data from the view by using a DBR or
DBRW function that references the view.
DBR(B5,"Department Store","Americas","Tents","Total Year",

"Budget version 1","Quantity")
In this example, the DBR function returns the value at the intersection of Department Store, Americas, Tents, Total
Year, Budget version 1, and Quantity in the view that is defined in cell B5.
You can also use cell references for some or all of the arguments:
DBR(B5,D55,D56,D57,D58,D59,”Quantity”)
Display the data source or package of a formula

When working in Dynamic Reports, Custom Reports and cell-based reports, you can use more than one data source or
package. You can synchronize the source tree when moving from cells of one data source or package to another.
Synchronizing the source tree enables you to see accurately the dimensional data used to populate the cells.
Right-click a formula cell and click IBM Planning Analytics > Display Package. The Task Pane displays the package or
data source that was used to create the selected cell.
Change the server and data source of TM1 formulas

Update the server and data source that formulas reference to switch from a test to a production environment, for
example, or to access information from a different set of financial data, such as a submission.
Procedure
1. From the worksheet you want to update, log on to the new server and select the data source.
2. To update all formulas in the report, do one of the following steps.
• If you are working with a Custom Report that you created from an Exploration View, edit the Cube in the
information area above the report. Use the format server:cube.
• If you are working with a Custom Report that you created manually, modify the cells where you defined the server
name and the cube name.
3. To update specific formulas, locate the formulas and modify the server:name parameter.
Tip: Use the Microsoft Excel search and replace function to update embedded references in the text of cell
formulas.
DBR and DBRW formulas

DBRW formulas are created, for example, when you create a Dynamic Report by converting an Exploration View or
Quick Report and when you convert an Exploration View to a Custom Report. DBRW formulas define the data cells. You
can also create your own DBR and DBRW formulas.
You can use several techniques to modify DBR and DBRW formulas.
You can modify the members that are used as arguments in DBR and DBRW formulas by using the following methods:
• Drag a member from the source tree onto a cell that contains a DBR or DBRW formula
• Use the Function Editor to modify the members that are used by a formula in a cell.
• Use the Function Editor to modify the members that are used by the formulas in a range of cells.

Modify DBR and DBRW functions by dragging members from the source tree
You can change the members that are used in a DBR or DBRW function by dragging members from the source tree.
Before you begin

You can drag members from the source to modify a DBR or DBRW function when the following conditions are met:
• The DBR or DBRW function includes a value for the server:cube parameter.
• You are connected to the data source referenced in the server:cube parameter.
Tip: To open the data source, right-click the cell and select IBM Planning Analytics > Display Package. The source
tree displays the data source.
Procedure
1. In the source tree, expand a dimension and locate the member that you want to use in the formula.
2. Click and drag the member onto the cell that contains the DBR or DBRW formula that you want to modify.
Results
The formula is updated in the worksheet.
Modify a range of DBR and DBRW functions

You can modify the DBR or DBRW functions that are used in a range of cells by using the DBR Function Editor.
Before you begin

The DBR Function Editor is available when the following conditions are met:
• The first cell in the range contain a DBR or DBRW function.
• All DBR or DBRW functions in the range have the same value for the server:cube parameter.
• You are connected to the data source referenced in the server:cube parameter.
Tip: To open the data source, right-click the cell and select IBM Planning Analytics > Display Package. The source
tree displays the data source.
About this task

You can select a range of cells that contain DBRW functions and change one or more members that are used by all of
the DBRW functions in the range. Dimensions that have multiple members within the range are not available for editing.
For example, if all DBRW functions in a column use Jan for the Month dimension and Europe for the Region dimension,
you can change Jan to Feb and Europe to France. If the member used for the Account dimension varies within the
column, the Account field is disabled in the DBR Function Editor. When you click OK, the DBRW functions in the column
are updated with Feb and France. All other members that are used by the DBRW functions remain unchanged.
Procedure
1. Select a range of cells.
2. Select the range and select the Insert Function button.
The Excel Function Editor is displayed. The Arguments list shows the parameter values that are used by the
functions. The members that are common to all of the cells in the range are available for editing.
3. Modify the members that are used in the parameters by using any of the following techniques:
• To specify a value directly, type a member name into the field. For example, to change the member for the first
dimension in the cube, type a member name into the first field.
• To use a cell reference, click . Click a cell and then click OK.
Note: You might need to scroll down in the Function Editor to see all of the parameters.
4. Click OK.
The functions are updated in the worksheet.
SUBNM formulas
SUBNM formulas are created, for example, when you create a Dynamic Report by converting an Exploration View or
Quick Report and when you convert an Exploration View to a formula-based report. SUBNM formulas define the context
members.
You can modify SUBNM formulas by using the set editor or by editing the formula.
You can also create your own SUBNM formulas.
To modify a SUBNM formula, double-click the cell. The set editor opens. Use the set editor to select members, and then
click OK. The formula is updated.
You can also edit SUBNM formulas manually.

Chapter 6. Cube viewer
You can work with data using the cube viewer rather than the Microsoft Excel grid. You can compare multiple cube
views alongside reports.
You can also generate reports from a cube view. See “Create a report” on page 115 for more information.
Procedure
2. In the source tree, navigate to the cube that you want to view, and expand Views.
3. Right-click a view and select Open in viewer.
A separate cube viewer opens. You can position it where you want in the window so that you can view it along side
other objects.
Data entry
You can enter data by typing in editable cells.
Cells that are grayed out and have data in italics in them, are read only. Cells can be read-only if you are a viewer, or if
the version that you are looking at is locked.
To enter dates, tap in a date cell and select the date.
Some cells have picklists that you can select from. The following image shows a picklist where you can select a
performance rating of Good, Average, or Poor.
Aggregated data is shown in bold. If you type data into an aggregated cell, the data is spread to the cells that make up
the aggregated cells.

Calculated cells at detail level are colored green. You can't directly update calculated cells by typing data in them.
Note: If all of the descendent detail cells are calculated, then you can't type data into the aggregated cell.
The following describes the areas that are referenced in the previous image:
1. Data can be entered in the Division row and in the 2016 column.
2. Aggregate data is bold. You can type data here.
3. Calculated cells are shaded green. You can't type data into calculated cells.
Symbols in cells, such as currency and percentages

In cells that expect numbers, you cannot enter a symbol. For example, in a cell that expects currency in dollars, you
enter the dollar amount in numbers, for example, for $10, enter 10.
If a cell is formatted as a percent %, the value is displayed as a proportion of 1. To enter 5%, you can either type 5% or
type 0.05. Both display as 0.05.
Preventing data from changing when data is spread

You can place a hold on a cell if you want to keep the value from changing when data is spread. Right-click the cell, then
select Hold and Release > Hold. You can still edit the cell directly. Two vertical bars indicate that a hold is active on a
cell.
When you place a hold on an aggregated cell, the aggregated value remains constant when you change any of the
children. When a hold is in place and you change the value of a child, proportional spreading is automatically applied to
the remaining children so that the consolidated value remains unchanged.
To remove holds, right-click any cell, then select Hold and release > Release all holds. You can also right-click a cell
with an active hold, then select Hold and release > Release hold to release a specific hold.
Zeroing data
You can replace data in a book view with zeros by going to a detail cell in the upper right corner and typing 0>|. This
copies 0 across rows (>) and columns (|).
Data display
You can change the position of dimensions in the cube viewer.
Dimensions can appear in several positions: on the row axis, on the column axis, or as context.
Procedure
1. To swap the position of dimensions in a cube, drop one dimension directly on top of another dimension.
2. To swap the position of the row and column dimensions, click .

3. To have two or more dimensions on a row, column, or the context area, drop one dimension next to another
dimension.
4. Dimensions that are used as context can be visible in the view or can be placed on the bench to save space and to
simplify the appearance of the view.
Sort rows and columns

You can sort labels or values in ascending or descending order. You can choose to sort by hierarchy, or to sort breaking
the hierarchy.
Procedure
1. To sort by label, right-click either the row selector , or the column selector ,
and select the sort option.
2. To sort by value, right-click in the row or column and select the sort option.
3. To sort values within a hierarchy, right-click on the hierarchy label, select Sort hierarchical, then choose your
option.
Show and hide totals

You can show and hide totals in a view, and choose whether totals are leading or trailing.
Procedure
Right-click either the row selector, or the column selector, and select one of the
Show totals options.
Cube viewer 111

Suppress zeros
You can hide rows and columns in a view that contain only zeros.
Procedure
Click and choose either rows or columns.
Expand levels
You can expand levels in a hierarchy to a specific depth.
You can expand levels manually by tapping , or by selecting a specific level from the menu.
Procedure
1. To select a specific level to expand from the menu, right-click the member in the row or column that you want to
expand.
A member that can be expanded has this icon: .
2. Select Expand to level, then select the level.
Display cell values as percentages

You can change the way values are displayed so that values are displayed as percentages of the total.
Procedure
1. Right-click in a cell, and select Show cell value as.
2. Select the appropriate option from one of the following:
% row total
Displays all the values in each row as a percentage of the total for the row.
% column total
Displays all the values in each column as a percentage of the total for the column.
% grand total
Displays values as a percentage of the total of all the values or data points in the report.
Advanced - % parent row total
Displays the values in each row as a percentage of the parent.
Advanced - % parent column total
Displays the values in each column as a percentage of the parent
The cells that display a percentage are shaded. This shading indicates that the values in these cells are calculated.
3. To return to the actual cell values, in the Show cell value window, select As-is.
Drill up or down on members

You can drill down on a consolidated member in a view to view the members of the consolidation and to hide other
members by double-clicking on the member.
Procedure
1. To drill up to next level, right-click and select Drill up.
2. To remove the drills, right-click and select View all.
Hide rows and columns

You can hide rows and columns that are not needed in a view.
Procedure
1. Right-click the columns or rows that you want to hide and select Hide.
2. Instead of hiding a member, you can select and right-click rows or columns that you want to keep, and select Keep.
All other rows or columns are hidden.
3. To unhide columns or rows that are hidden, right-click and select Unhide all.
Add a calculation to a view

Member calculations apply to one or more members on either the row or column axis of a view.
About this task

You can create the following calculations with one member selected:
• Rank: ranks the value of the cell, with rank 1 being the highest. This applies to visible numeric values only.
• Absolute value: the non-negative value of the cell.
• Percentage (%) of total: the value as a percentage of the total.
• Percentage (%) of parent: the value as a percentage of the immediate parent.
• Selected member + (plus), -(minus), / (divided by) or * multiplied by a numeric value (or the reverse)
You can calculate the following calculations with two or more members selected,
• Average
• Minimum
• Maximum
• Median
With just two members selected, you can create the following calculations:
• Member 1 * member 2
• Member 1 + member 2
• Member 1 - member 2
• Member 1 / member 2
• Member 1 % change member 2
• Member 1 % of member 2
You can reverse the members in calculations by tapping
Procedure
1. Right-click the row or column label of the member for which you want to create a calculation.
To create a calculation on multiple members, use CRTL+click or SHIFT+click to select the member labels, and then
right-click on one of the selected member labels.
2. Click Calculations, then Create.
3. Optionally, enter a name for the calculation. This is the name that will appear as a row or column label in your view.
If you don't enter a name, a name is assigned.
4. Click the calculation you want to create.
5. If you are creating an arithmetic calculation on a single member, enter the required numeric value.
Cube viewer 113

6. Click OK.
Sandboxes
Sandboxes let you try out different changes to the data before making those changes public to other users and before
committing those changes to the base data. Sandboxes are visible only to you.
Procedure
1. To create a sandbox, click and tap Create sandbox.

2. Name the sandbox.
3. Choose whether you want to create a sandbox from the base data or to create a copy of an existing sandbox, and
then click OK.
You can now work in the sandbox. You can move between different sandboxes by selecting them from the drop-
down list.
4. When you are satisfied with the data in a sandbox, and you want to commit it to the base, click Commit data.
5. To delete a sandbox, follow these steps.
a) Click .
b) Select Delete sandbox, select the sandbox that you want to remove, and tap Delete.
Copy and paste

You can paste values from external applications, or from such as Microsoft Excel.
User interface
Support for the right-click user interface varies by browser. Some browsers display cut, copy, and paste options when
you right-click a cell or range of cells; others do not. However, all browsers support keyboard shortcuts:
• CRTL+x - cut
• CTRL+c - copy
• CRTL+v - paste
Paste behavior
When you paste to a single cell, the contents of the clipboard are pasted with the selected cell as the initial insertion
point, and the paste operation expands to other cells as required.
When you paste to a selected range of cells, and that range is smaller than contents of the clipboard, you are notified
that the paste operation will modify cells beyond the selected range. You have the option of accepting or canceling the
paste operation.
There is a 60,000 cell limit for pasting into the cube viewer. If you try to paste more than 60,000 cells an error will be
displayed.
Data spreading
You can use data spreading options to detail cells to distribute numbers in cells in a grid. For example, you can evenly
distribute a value across a range of cells.
You can use data spreading options with copy and paste shortcuts and data entry commands. To find out more, see
“Copy and paste” on page 114 and “Quick data entry commands” on page 116.
By default, the spreading options replace data, but you can specify + or ~ to add or subtract data instead.
Proportionally spread a value
P
Example: P<>100
Proportionally spreads the value 100 to all detail cells on the row of insertion and replaces the existing cell values.
Equally spread a value
S
Example: S+|^200
Equally spreads the value 200 to all detail cells on the column of insertion, and adds the product of spreading to the
existing cell values
Repeat a value
R
Example: R~<50
Subtracts the value 50 from all detail cells to the left of the insertion point.
Apply a percent change
P%
Example: P%+<>10
Takes 10 percent of the cell values and adds it to the existing cell values across the row.
Populate cells by specifying a start and end value (Straight-line)
SL
You specify a start and end value, choose the direction of the spread, and the update action.
Example: SL>100:200
Replaces all detail cell values to the right of insertion with a start value of 100 and an end value of 200. Across 5
detail cells, the values would be:
100, 125, 150, 175, 200.
Apply a linear growth percentage
GR
You specify a start value and a growth percentage.
Example: GR |300:25
Applies a 25 % growth percentage to the starting value of 300 and replaces all detail values below the point of
insertion.
Create a report
You can create an Exploration View, Dynamic Report, Quick Report and a Custom Report from a View in the cube view.
Procedure
1. Open the cube view, and click .

2. Select the kind of report you want to create: Exploration View, Dynamic Report, Quick Report, or Custom Report.
The report is created in an Excel worksheet.
Cube viewer 115

Multiple hierarchies
IBM TM1 dimensions can include one or more hierarchies. Currently, multiple hierarchies can be implemented by using
TurboIntegrator or Planning Analytics Workspace.
Exploration Views and Quick Reports can display more than one hierarchy in a dimension.
If you are working in an IBM Planning Analytics data source where multiple hierarchies are enabled, and are in use, you
can do the following tasks in the Cube viewer.
• Remove hierarchies
• Hide a hierarchy control from view and add to the bench.
• Add a new related hierarchy from the same parent dimension to the view
• Replace a hierarchy with a different hierarchy.
Note: Do not create Dynamic Reports, or Custom Reports containing multiple hierarchies, as you will get errors.
Procedure
1. In the source tree, navigate to the cube that you want to view, and expand Views.
2. Right-click a view and select Open in viewer.
3. In the overview, right-click the dimension member, and select one of these options:
Remove this hierarchy
Remove this hierarchy from the view.
Hide from view
Hide this hierarchy control from the view and add to the bench.
Add related hierarchy
Adds a new related hierarchy from the same parent dimension to the view. Select the hierarchy and click Insert.
Replace this hierarchy
Replace this hierarchy with a different hierarchy. Choose the hierarchy that you want to replace it with.
Quick data entry commands

You can type a data entry command into a cell in a grid.
You can combine most of these commands with the copy and paste commands and with data spreading techniques. To
find out more, see “Copy and paste” on page 114, and “Data spreading” on page 115.
Enter the value in thousands
K
Example: 5K
Enters 5,000
Enter the value in millions
M
Example: 10M
Enters 10,000,000.
Add a number to a cell value
Add, +
Example: Add50
Adds 50 to the cell value.
Subtract a number from the cell value
Subtract, Sub, ~
Important: A minus sign (-) can't be used for subtract because it indicates a negative number.
Example: sub8
Subtracts 8 from the cell value.
Multiply the cell value by a percentage
Percent, Per
Example: per5
Gives 5% of the original cell value
Increase the cell value by a percentage
Increase, Inc
Example: inc10
Increases the cell value by 10%
Decrease the cell value by a percentage
Decrease, Dec
Example: Dec6
Decreases the cell value by 6%
Grow cells by a percentage
Gr
Example:Gr>150:10
Increase the value by 10 percent starting with a value of 150.
Hold the cell value from breakback calculations
Hold, Hol, H, Hc
Hc holds aggregated cells.
Release held cells
Release, Rel, Rh, Rc
Rc releases aggregated cells.
Release all held cells
RA
Cube viewer 117

Chapter 7. Action buttons
You can create action buttons to run processes, navigate between worksheets, and recalculate worksheets.
Users can access these buttons when working in IBM Planning Analytics for Microsoft Excel or with websheets in TM1
Web.
You can use an action button to perform any of the following tasks:
• Run a TurboIntegrator process.
• Navigate to another worksheet.
• Run a TurboIntegrator process and then navigate to another worksheet.
• Recalculate a worksheet or rebuild a TM1 Dynamic Report in a worksheet.
For example, suppose that you have a workbook containing many worksheets. The workbook is large and you want to
make it easier to use and to maintain.
You can place action buttons on the first sheet to enable users to navigate quickly to the worksheets within the book.
You can also configure the action buttons to navigate to a worksheet and then recalculate it.
You can also create a worksheet with action buttons to run the TurboIntegrator processes you use to maintain the
reports in the workbook, for example.
You can also use an action button on a worksheet with a Dynamic Report to rebuild the report.
What action buttons do

When you click an action button, the steps that are performed depend on how the action button was configured.
When an action button runs a TurboIntegrator process only, IBM Planning Analytics for Microsoft Excel performs the
following steps:
1. If you selected a calculation operation on the Calculate tab, the calculation operation is performed.
2. The TurboIntegrator process is run.
3. The calculation operation that you selected in the Options dialog box for the process is performed.
When an action button navigates to a worksheet only, IBM Planning Analytics for Microsoft Excel performs the following
steps:
2. The navigation action begins.
3. Target values are set in the target worksheet. If you specified mappings in the Advanced Options dialog box, the
mappings are applied.
4. The calculation operation that you selected on the Worksheet tab of the Action Button Properties dialog box is
performed on the target worksheet.
When an action button runs a TurboIntegrator process and then navigates to a worksheet, IBM Planning Analytics for
Microsoft Excel performs the following steps:
2. The TurboIntegrator process is run.
3. The calculation operation that you selected in the Options dialog box for the process is performed.
4. The navigation action begins.
5. Target values are set in the target worksheet. If you specified mappings in the Advanced Options dialog box, the
mappings are applied.
6. The calculation operation that you selected in the Worksheet tab of the Action Button Properties dialog box is
performed on the target worksheet.
When an action button recalculates a worksheet or rebuilds a Dynamic Report only, IBM Planning Analytics for
Microsoft Excel performs the following steps:

1. The calculation operation that you selected in the Calculate tab of the Action Button Properties dialog box is
performed on the worksheet.
Add to a worksheet
You can insert an action button into a worksheet.
Before you begin

You must enable the following Microsoft Excel setting: Trust access to the VBA project object model. This setting is
found in Options, Trust Center Settings, Macro Settings.
About this task

When you insert an action button, you configure the action button and set its appearance properties.
The action buttons that you create are listed in the source tree under Action Buttons.
You can modify an action button. In the source tree, expand Action Buttons. Right-click an action button and select
Edit.
Procedure
1. Go to the worksheet where you want to add the action button.
2. On the IBM Planning Analytics toolbar, click the Action Button .

The Action Button Properties dialog box is displayed.
3. Select the TM1 Server Application Folder where your data is located and connect to the server.
a) Select the TM1 Server.
For example, if you want to run a TurboIntegrator process that is stored on a different TM1 server, select the
server.
You can use a cell reference or a named range to retrieve the TM1 server name dynamically. Click the Use
Reference check box and then enter a cell or named-range reference.
To select a cell reference, click and then specify the cell where the server name is located.
To retrieve the server name by referencing a named range, use the following format:
=NameOfRange
The named range must point to a single cell that contains text for the server name.
b) If you are not connected to the server that you want to use, click Connect and log in.
4. Click the action that you want the action button to perform.
5. Configure the action button.
For more information, see the following topics:
• “Run a process” on page 121
• “Navigate to another worksheet” on page 121
• “Run a process and navigate to a worksheet” on page 124
• “Recalculate or rebuild a worksheet” on page 124
6. Set the appearance of the action button. For more information, see “Set the appearance” on page 125.
7. Click OK.
What to do next
Action buttons can be saved in a workbook. If the saved workbook has Protected View enabled, the user opening the
workbook must select the Enable all macros option under File > Options > Trust Center > Trust Center Settings... >
Macro Settings.
Run a process
You can use an action button to run a TurboIntegrator process.
Procedure
1. Create an action button. For more information, see “Add to a worksheet” on page 120.
2. In the Action Button Properties dialog box, click Run a TurboIntegrator Process.
The Process tab is displayed.
3. Select the process that you want to run.
a) To select a process from the server that is displayed in the TM1 Server list, click the Process list and select a
process.
b) To select a process from the current workbook, click the Process list and select Get Process info from
Worksheet. In the Process Name box, enter the process name or click and specify a cell reference or a
named range.
4. Specify parameters, if any, for the process. The Parameters table shows the available parameters for the process
you selected.
To specify a value for a parameter directly, enter the value in the Value cell and then press Enter.
To use a cell reference or a named range, click the Value cell and then click . Specify the cell reference or a
named range, and then click OK.
5. Click Options. The Options dialog box is displayed.
6. Select the calculation operation that you want to occur after the process runs.
• Automatically Recalculate Sheet - Refreshes the data in the current worksheet.
• Rebuild Sheet - Equivalent to Automatically Recalculate Sheet. Rebuilds the TM1 Dynamic Report to its original
report definition configuration.
• None - Do not recalculation or rebuild the worksheet.
7. Select and type the messages that you want the action button to display.
• Show Success Message - Displays a message after the process runs successfully.
• Show Failure Message - Displays a message if the process does not run successfully.
• Show Confirmation - Displays a confirmation message before the process is run. The user can click Yes or No.
8. Click OK. The Action Button Properties dialog box is displayed.
9. If you want to recalculate or rebuild the worksheet before the TurboIntegrator process runs, click the Calculate tab
and select an option.
10.Set the appearance of the action button. For more information, see “Set the appearance” on page 125.
11.Click OK.
Navigate to another worksheet

You can use an action button to navigate to another worksheet in the same workbook, or to a worksheet in another
workbook.
Procedure
2. In the Action Button Properties dialog box, click Go to another Worksheet.
The Worksheet tab is displayed.
3. Specify the target workbook.
• To select a workbook on a TM1 server, click TM1 Applications. Click Browse and select the workbook.
Or, to use a cell reference or a named range for the workbook name, click . The referenced cell or named
range must contain the path to the workbook. Start with the first folder name under Applications and use a back-
Action buttons 121

slash \ character to separate folders. Do not include the Applications folder in the path. For example: Planning
Sample\Bottom Up Input\Budget Input.
• To select a workbook that is stored on your computer or on the network, click Files. Click Browse and select the
workbook.
Note: If you plan to share your workbook with TM1 Web or IBM Planning Analytics Workspace users, place the
target workbook in a shared network location. The location that you specify must be accessible by the server
where TM1 Web or IBM Planning Analytics Workspace is running.
4. Specify the target worksheet.
You can use any of the following techniques.
• Click the Sheet list and select a worksheet.
• Enter the worksheet name in the Sheet field. Use the following format: =SheetName!Cell
• Use a cell reference or a named range, click . Specify the cell reference or a named range, and then click OK.
5. Set the following options.
• Match Title Elements - Automatically matches and sets the text of the title dimensions in the target worksheet
when a user clicks the action button. For more information, see “Match Title Elements option” on page 123.
• Replace Current Workbook - Determines whether the target worksheet opens in a new window or in the same
window, replacing the source worksheet. For more information, see “Replace Current Workbook option” on page
124.
6. Select the calculation operation that you want performed on the target worksheet.
• None - Do not recalculation or rebuild the worksheet.
7. To map items, click Advanced Options.
For more information, see “Map fields” on page 122.
8. If you want to recalculate or rebuild the worksheet before navigating to the target worksheet, click the Calculate tab
and select an option.
10.Click OK.
Map fields
When you create an action button that navigates to another worksheet, you can manually map fields between the
source worksheet and the target worksheet. You can map dimensions, cells, and values from the source worksheet to
the target worksheet.
Note: Manual mapping is applied after any automatic mapping has been applied by the Match Title Elements option.
To map fields, click Advanced Options on the Worksheet tab in the Action Button Properties dialog box.
The Advanced Options dialog box includes a grid where you define the mapping of fields between the source and target
worksheets. Use the Add and Delete buttons to manage the rows in the grid.
You map the source worksheet to the target worksheet by setting values for the source type, source object, target type,
and target object in the Advanced Mapping grid.
Use the following steps to configure advanced mapping:
1. Indicate the type of object to map by setting the Source Type.
2. Determine the value for the type of object you are using by setting the Source Object.
3. Indicate the type of cell to map by setting the Target Type.
4. Indicate where to insert the value from the source object by setting the Target Object.
5. Repeat these steps to create more mapping configurations.
Source Type
The Source Type field represents the type of object for the value you want to map.
• SUBNM - Indicates that you are mapping from a cell that contains a title dimension in the source worksheet.
• Selected DBRW - Indicates that you are mapping from a cell that contains a DBRW formula in the source
worksheet.
• Value - Indicates that you will enter a string or numeric value to send to the target worksheet.
Source Object
The Source Object field takes a value, or a Microsoft Excel expression that evaluates to a value, depending on what
you selected in the Source Type field.
• If Source Type is set to SUBNM, specify the name of the title dimension that exists in the source worksheet.
• If Source Type is set to Selected DBRW, specify the name of a row or column title dimension that exists in the
source worksheet.
• If Source Type is set to Value, enter a string or numeric value to send to the target worksheet.
Note: You can also retrieve these values from the source worksheet by using a cell reference or a named range.
Target Type
The Target Type field specifies the type of cell in the target worksheet where the value from the Source Object field
will be inserted.
• SUBNM - Indicates that the target is a title dimension in the target worksheet.
• Named Range - Indicates that the target is a named range in the target worksheet.
• Range - Indicates that the target location is a cell in the target worksheet.
Note: If you set Target Type to either Named Range or Range, any pre-existing data or formula in the target cell
will be overwritten when you click the action button. If the target cell contains a DBRW function, then the function
will be lost and the cell will not be able to connect to, read from, or write to the IBM TM1 server.
Target Object
The Target Object specifies the location in the target worksheet where the value from the source object will be
inserted. This location can be the name of a title dimension, a specific cell location, or a named range in the target
worksheet, depending on what you selected for Target Type.
• If Target Type is set to SUBNM, specify the name of the title dimension in the target worksheet. When Target
Type is set to SUBNM, you must also enter a value for the Subset and Alias fields.
• If Target Type is set to Named Range, specify the name of the range in the target worksheet.
• If Target Type is set to Range, specify the cell location in the target worksheet.
You can enter a value for the target object by entering the location value directly. Or, you can use a cell reference or
a named range to retrieve the location.
• Entering a value directly: To identify a location in the target worksheet, enter the value directly into the Target
Object field without the equal sign =. For example, enter C3 to identify the location of the target object as the cell
C3 of the target worksheet.
• Using a cell reference or a named range: To reference a cell in the source worksheet that contains a location for
the target object, include the equal sign =. For example, the cell A1 in the source worksheet might contain the
value C3 to represent the cell location for the target object in the target worksheet.
Match Title Elements option

The Match Title Elements option automatically matches and sets the text of the title dimensions in the target
worksheet when a user clicks an action button to navigate to the target worksheet.
The Match Title Elements option is displayed on the Worksheet tab of the Action Button Properties dialog box.
When the Match Title Elements option is enabled, the dimensions in the source and target worksheets are
automatically matched by the SUBNM and DBRW functions as follows:
• TM1 automatically matches title dimensions in the source and target worksheets based on the SUBNM formula in a
cell.
For example, when the same dimension exists in both the source and target worksheets, the member selected in the
source worksheet is set for the same dimension in the target worksheet. When a column is selected in the source
worksheet, it matches to the column with the same title dimensions in the target worksheet.
Action buttons 123

• TM1 automatically matches the row and column dimensions of the currently selected DBRW cell in the source
worksheet to the matching title dimensions in the target worksheet, if they exist.
For example, if Operating Expense and Feb-2015 are the row and column dimension members for the currently
selected member in the source worksheet, when navigating, these dimension members are matched to the title
dimensions in the target worksheet. If the row Operating Expense and the column Feb-2015 are both selected in the
source worksheet, the DBRW cell is the cell that exists in both the Operating Expense row and the Feb-2015 column.
The row and column dimensions of the DBRW cell are matched to title dimensions in the target worksheet.
Replace Current Workbook option

The Replace Current Workbook option determines whether the target worksheet is opened in a new window or in the
same window, replacing the source worksheet.
The Replace Current Workbook option is displayed on the Worksheet tab of the Action Button Properties dialog box.
For example:
• If Replace Current Workbook is not selected (default) and you are working in TM1 Web, then the source worksheet
remains open and the target worksheet opens in a new tab.
• If Replace Current Workbook is selected and you are working in TM1 Web, then the source worksheet is replaced by
the target worksheet on the same tab and a new tab does not open.
Important: If you enable the Replace Current Workbook option, remember to save your workbook before you test the
new button. You could lose your changes if you click the button and cause the current workbook to close.
Run a process and navigate to a worksheet

You can configure an action button to run a TurboIntegrator process and then navigate to another worksheet.
Procedure
2. In the Action Button Properties dialog box, click Run a Process, then go to another Worksheet.
The Process tab is displayed.
3. Select the process that the action button will run. See “Run a process” on page 121.
4. Select the worksheet to which the action button will navigate. See “Navigate to another worksheet” on page 121.
6. Click OK.
Recalculate or rebuild a worksheet

You can use an action button to recalculate or rebuild a worksheet, without running a TurboIntegrator process or
navigating to a new worksheet. You can also use the Calculate tab to select the calculation operation that you want the
action button to perform before running a TurboIntegrator process or navigating to another worksheet.
Procedure
2. In the Action Button Properties dialog box, click Calculate/Rebuild Only.
The Calculate tab is displayed.
3. Select the calculation option that you want to use.
• None - Do not recalculate or rebuild the worksheet.
5. Click OK.
Set the appearance
You can set the appearance of action buttons. You can set the caption, background picture, and other visual features for
the action button.
In the Action Button Properties dialog box, click the Appearance tab to adjust the appearance of the button.
The Appearance tab has the following options:
• Caption - Sets the caption text that displays on the button.
Tip: Use a single space character if you want to have a blank caption. Leaving the caption empty may result in the
action button caption appearing as "Run" when opened in other applications.
• Resize Button to Caption – Adjusts the size of the button to fit the caption.
• Font - Displays a font dialog box where you can change the font type and size of the button caption.
• Show Background Image - Use this option to select a background image for the button. Click Browse to select an
image file (bmp, gif, or jpg format). The image will be stretched to fit the size of the button.
• Display as Hyperlink - When enabled, this option displays the button as a hyperlink with blue, underlined text
instead of as a standard button. This option is not available if Show Background Image is selected.
• Preview - This area shows an example of what the button will look like.
• Colors - Use these options to set text and background colors for the button. Click the color sample to display a Color
dialog box where you can select a standard color or define a custom color. If you select Display as Hyperlink, the
color options do not apply.
Edit, copy, rename, or delete

You can modify, copy, rename, or delete an action button.
In the source tree, click the Workbook tab, and expand Action buttons.
To modify an action button, right-click the action button in the source tree and select Edit.
To copy an action button, drag and drop the action button from the source tree onto the worksheet.
Note: Action buttons cannot be copied to another workbook. Copying an action button will not copy the visual
formatting of the action button.
To rename an action button, right-click the action button and type the new name. To refresh the name in the Action
buttons list, right-click Action buttons and then click Refresh list.
To delete an action button, right-click the action button in the source tree and select Delete.
Tip: To see where an action button is located in a workbook, right-click the action button and select Select.
If you do not see your action button in the source tree, right-click Action buttons and then click Refresh list.
Action buttons 125

Chapter 8. IBM API
Using an application programming interface (API), you can automate the refreshing or publishing of content.
About this task

You can use the API to create a scheduled batch program to refresh content on a daily, weekly, or monthly basis so
that, as your period data changes, the affected files are kept up-to-date.
You can call the API within Microsoft Excel workbooks using VBA or using VBS and a command line interface. For these
types of automation to work, you must register one or more macros within the workbook.
If you have IBM Cognos Office installed, you can also use the API in Microsoft Word and Microsoft PowerPoint.
When using sample macros and script files as part of your own processing functions, remember that the API is
accessible only as user defined functions (UDFs). UDFs are functions created in Visual Basic for Applications (VBA). In
this case, however, the UDFs are created within the IBM Cognos solution and are called from VBA.
To help you understand what is possible using this API, several samples are provided. You can use the samples to help
you create your own solutions.
• Creating VBA macros
• Passing parameters, leveraging VBS and the command line interface
In addition to these capabilities, you can schedule scripts, either ones that you create or the samples, to run as a batch
process at a set time.
To use automation, you must set your macro security to an appropriate level in your Microsoft application. You can set
the macro security level using one of the following options depending on your version of Microsoft Office.
• Change the security level of your Microsoft application to medium or low.
• Change the trusted publishers setting of your Microsoft application so that installed add-ins or templates are trusted.
Set up
The quickest way to set up automation is to import the CognosOfficeAutomationExample.bas file into the
Microsoft application.
These files contain all the necessary macros, including the CognosOfficeAutomationObject macro. Alternatively, you
can create templates that already contain this imported .bas file that supply the code for logging on to IBM Cognos
application, refreshing the content of specified workbooks, documents, or presentations, and logging off.
After the reference to IBM Cognos automation is established, any macro in VBA can call the functions exposed in the
IBM Cognos automation API.
If the Microsoft application is open when a command is executing, the command executes in interactive mode. If the
Microsoft application is closed when the command is executing, the command executes in batch mode. Executing in
batch mode means that all display alerts are turned off.
Because the object is obtained at run time and there is no type library installed on the client machine, you cannot use
IntelliSense to determine what properties and methods are available on the object.
Before you begin

To use the IBM Cognos automation macro files, you must import the CognosOfficeMessageSuppressor.cls file. The .cls
file contains the SuppressMessages function that allows you to disable the standard alerts and messages.
Procedure
1. Open a new Office document, workbook, or presentation.
2. Customize the ribbon to display the Developer tab.

3. Click the Developer tab, and then click Visual Basic.
4. Do the following based on the Microsoft Office application you are using:
• For Microsoft Excel and Microsoft PowerPoint, right-click VBAProject and click Import File.
• For Microsoft Word, right-click Project and click Import File.
The Import File dialog box appears.
5. Browse to the location where the IBM Cognos Automation macro files are installed.
The default location is client_installation_directory\Automation.
6. For Microsoft Excel or Microsoft Word click the CognosOfficeAutomationExample.bas file or for Microsoft
PowerPoint click the CognosOfficeAutomationPPExample.bas file and import it into the VBA project.
Do not edit this code module. Do not import both files, which are application specific. This will cause problems for
the Open routine.
7. Repeat steps 3 to 5 to import the CognosOfficeMessageSuppressor.cls file.
8. Close the Visual Basic Editor and return to the IBM Cognos application.
9. Save the file as a template, close it, and then reopen the template file.
Results
You can now call the macros contained in the Cognos automation macro files from the VBA code that you write in Excel,
Word, or PowerPoint.
Log automation activities and errors

Use the automation log to track automation activities and troubleshoot problems with automation tools and scripts.
The automation log is automatically generated when you run an automation script.
The automation log is returned using a call to the Automation API function TraceLog. For information about the
TraceLog function, see “TraceLog ” on page 134.
Global API functions

Global API functions can be used to interact with any IBM Planning Analytics for Microsoft Excel worksheets.
The global functions that are exposed through the IBM Cognos automation objects are:
ClearAllData
ClearAllData clears all data values in the opened workbooks.
Syntax
ClearAllData()
Example
The following syntax is an example:
CognosOfficeAutomationObject.ClearAllData
ClearBook
ClearBook clears IBM Planning Analytics for Microsoft Excel data in the active book.
Syntax
ClearBook()
Example
Application.COMAddIns("CognosOffice12.Connect").Object.AutomationServer.Application("CO
R", "1.1").ClearBook
ClearCache
ClearCache reduces the size of an IBM Planning Analytics for Microsoft Excel workbook by clearing metadata and data
from formulas.
Syntax
ClearCache()
Example
The following is an example of the syntax:
CognosOfficeAutomationObject.ClearCache()
ClearSelection
ClearSelection clears IBM Planning Analytics for Microsoft Excel data in the active selection.
Syntax
ClearSelection()
Example
R", "1.1").ClearSelection
ClearSheet
ClearSheet clears IBM Planning Analytics for Microsoft Excel data in the active sheet.
Syntax
ClearSheet()
Example
R", "1.1").ClearSheet
HttpLogonCredentials
The HttpLogonCredentials function authenticates a user to a Web site that requires new authentication credentials,
such as Basic, Kerberos, and SiteMinder. HttpLogonCredentials takes the URL, user name, and password that are used
for authentication on the Web site.
IBM Cognos does not support SiteMinder form-based authentication. You must use the IBM Cognos menu commands
and options instead of the API to automate the refreshing and publishing of content.
Syntax
HttpLogonCredentials (url, user name, password)
IBM API 129

Table 14: Arguments for HttpLogonCredentials
Argument Description Data type
url The URL for the Web site against which String
you want to authenticate
user name The user name for authentication String
password The password for authentication String
Logoff
Logoff logs off all the IBM Cognos servers to which users are currently logged on.
Syntax
Logoff()
Example
CognosOfficeAutomationObject.Logoff
Logon
The Logon function takes the URL of the server and the credential elements required by IBM Cognos to perform a
logon: user ID, password, and namespace. The namespace parameter is case-sensitive; therefore, you must match the
namespace exactly.
IBM Cognos Office stores user credentials only in memory. For this reason, users are responsible for storing their
credentials in a secured area and passing them to the logon methods at run time.
If you use the Logon function with incorrect credentials, the system raises a CAMException error, however, no exception
is written to the log file indicating a failure. To avoid this situation, remember that strings are case-sensitive and ensure
that you use valid user IDs, passwords, and namespaces.
Logon does not appear in the macro list in the Microsoft application because the macro receives an argument. Any
macro with parameters is by definition private and private macros are not shown in the macro options by default.
Syntax
Boolean Logon (url, user name, password, namespace)
Parameters
Table 15: Arguments for Logon

url The URL for the IBM Cognos server to which you want String
to log on
user name The user name for authentication String
password The password for authentication String
namespace The specific namespace for authentication String
Return value
Data type: Boolean
The Boolean value that is true if successful
Example
Here is an example of this syntax:
Dim bResult As Boolean
bResult = CognosOfficeAutomationObject.Logon
("http://localhost/ibmcognos/cgi-bin/cognos.cgi",
"Administrator", "CognosAdmin", "Production")
Publish
Use Publish to publish content to IBM Cognos Connection or to a TM1 Server Application Folder.
The arguments mirror the entry boxes in the dialog box that is used in the user interface.
Publish does not appear in the macro list in the Microsoft application because the macro receives an argument. Any
macro with parameters is by definition private and private macros are not shown in the macro options by default.
Syntax
Publish (URL, document path, server path, name, description, screenTip)
Parameters
Table 16: Parameters for the Publish macro
URL The server to which you are publishing. String
document path The location of the document to be published. It is the local path of the file that you String
want to publish. If the path of your folder is not correct when you publish using
automation, you are again prompted to log on. This is because IBM Cognos does not
distinguish between non-existing folders and folders for which the user does not
have permissions. This security feature helps to prevent the discovery of the folder
path by trial and error.
server path The path in the content store where the document is saved. String
name The document name that will appear in IBM Cognos. String
description The document description that will appear in IBM Cognos. String
screenTip The text that users see when they point to the document in IBM Cognos. String
Example
Following is an example of this syntax:
Publish("CAMID('::Anonymous')/folder[@name='My
Folders']","Description of 'My Folders'", "")
IBM API 131

RefreshAllData
RefreshAllData fetches the most current data values from the IBM TM1 server and updates those values in the current
document.
The system must be successfully logged on to the IBM TM1 server.
Syntax
RefreshAllData()
Example
The following is an example of this syntax:
Dim bResult as Boolean
'Refresh the data if we successfully logged on to the

IBM Cognos server.
If bResult Then
CognosOfficeAutomationObject.RefreshAllData
End If
RefreshAllDataAndFormat
RefreshAllDataAndFormat retrieves the most current data values and formatting from the IBM Cognos server and
updates those values and formats in the current document.
The system must be successfully logged on to the IBM Cognos server.
Syntax
RefreshAllDataAndFormat()
Example
The following example shows how the RefreshAllDataAndFormat method is used:
'Refresh the data and formatting if we successfully logged on to the

IBM Cognos server.
If bResult Then
CognosOfficeAutomationObject.RefreshAllDataAndFormat
End If
RefreshSelection
RefreshSelection refreshes IBM Planning Analytics for Microsoft Excel data in the active selection.
Syntax
RefreshSelection()
Example
R", "1.1").RefreshSelection
RefreshSheet
RefreshSheet refreshes IBM Planning Analytics for Microsoft Excel data in the active sheet.
Syntax
RefreshSheet()
Example
R", "1.1").RefreshSheet
SuppressMessages
SuppressMessages suppresses the standard alerts and messages that are shown during the normal operations of IBM
Cognos applications.
Syntax
SuppressMessages()
Example
Private Sub Class_Initialize()
CognosOfficeAutomationObject.SuppressMessages True
End Sub
Private Sub Class_Terminate()
CognosOfficeAutomationObject.SuppressMessages False
End Sub
TraceError
TraceError appends error information into the IBM Planning Analytics for Microsoft Excel log file. The user defines the
error information they wish to append to the log file for errors.
IBM API 133

Syntax
TraceError("<user defined error information>")
Example
Application.COMAddIns("CognosOffice12.Connect").Object.AutomationServer.TraceError("VBA
method failed")
Example
The following is an example of the appended error information in the IBM Planning Analytics for Microsoft Excel log file:
[Severity=Error]
[Exception] TraceError(String error)
[Thread=6, Background=True, Pool=True, Domain=]
[System.Exception] VBA API ERROR: VBA method failed
TraceLog
TraceLog returns all the automation activities and errors.
Syntax
String TraceLog()
Return value
Data type: String
The value of the logging item as string
Example
Dim strTraceLog as String
strTraceLog = CognosOfficeAutomationObject.TraceLog
MsgBox strTraceLog
UnlinkAllData
UnlinkAllData disconnects all the IBM Cognos data values in the current document. The values are no longer updated
with subsequent calls to RefreshAllData. The values become static.
For IBM Cognos Office, any IBM Cognos data values that are imported into the current document after UnlinkAllData is
called will continue to be linked to the IBM Cognos data source.
The values can be updated with new server data using the RefreshAllData call.
Syntax
UnlinkAllData()
Example
CognosOfficeAutomationObject.UnlinkAllData
UnlinkBook
UnlinkBook unlinks the active book from the connection.
Syntax
UnlinkBook()
Example
R", "1.1").UnlinkBook
ClearBook
Clear Book clears IBM Planning Analytics for Microsoft Excel data in the active boo
Syntax
UnlinkSelection()
Example
R", "1.1").UnlinkSelection
UnlinkSheet
UnlinkSheet unlinks the active sheet from the connection.
Syntax
UnlinkSheet()
Example
R", "1.1").UnlinkSheet
UpdateServerUrl
Use UpdateServerUrl to update the IBM Cognos server information for existing reports and formulas.
The UpdateServerUrl method takes two arguments: the old server URL and the new server URL. These arguments
mirror the entry boxes in the Update System dialog box. To gain access to this control from IBM Cognos, click the
Options button on the IBM Cognos ribbon, then click Update System Utility.
The UpdateServerUrl method replaces the server information for existing reports. When running this command, the
name of the package or data source remains the same. You can use this method to change only one server, such as a
test server to a production server. The URL arguments can be full or partial URLs. If any argument is empty, this
command does nothing, however, running this command with empty arguments has the potential to corrupt the report.
Server information is stored in both the server property and the serialized report property. Running an empty command
could cause these two instances to get out of sync.
Because the UpdateServerUrl method searches and replaces strings, it is possible to use only part of the URL, provided
it is a unique substring.
IBM API 135

Note: The UpdateServerUrl search looks at all data in the workbook and updates data that matches the search string,
not just report properties containing the URL string. Therefore, when you use only part or all of the original URL string
with the UpdateServerUrl method, you will change all data that matches the search string
Syntax
UpdateServerUrl "old server URL string" "new server URL string"
Parameters
Table 17: Parameters for the UpdateServerUrl method
old server URL string Indicates the URL of the source or current system. String
new server URL string Indicates the URL of the target system. String
Example
The following example uses the complete URL:
UpdateServerUrl "http://testserver1/cgi-bin/cognos.cgi"
"http://prodserver1/cgi-bin/cognos.cgi"
The following example uses only the part of the URL that is changing:
UpdateServerUrl "testserver1" "prodserver1"
Wait
Wait holds the VBA thread until all prior IBM Planning Analytics for Microsoft Excel background tasks are complete.
Syntax
Wait()
Example
R", "1.1").Wait
Usage example
The following are examples of the usage:
Sub Wait()
Reporting.GetCurrentReport(ActiveCell).Commit
Reporting.Wait
Reporting.GetCurrentReport(ActiveCell).Refresh
End Sub
Sub Wait()
R", "1.1").RefreshBook
R", "1.1").Wait
MsgBox "Refresh complete!"
End Sub
Exploration API functions

Exploration functions can be used to interact with exploration worksheets.
The exploration functions that are exposed through the IBM Cognos automation objects are:
Clear
Clear is used to clear all of the data values in the exploration.
Syntax
Reporting.Explorations.GetAt().Clear
Example
Public Sub Clear()

Reporting.Explorations.GetAt(Application.ActiveSheet.Name).Clear
End Sub
Create
Create generates an Exploration View based on the host system URL, server name, cube name, and view name.
Syntax
Explorations.Create "<host system URL>", "<server name>", "<cube name>",

"<view name>"
Parameters
Table 18: Arguments for Create

host system URL URL of the host system which the Exploration View is Alphanumeric string
to be created from
server name Name of the server which the Exploration View is to be Alphanumeric string
created from
cube name Name of the cube which the Exploration View is to be Alphanumeric string
created from
view name Name of the view which the Exploration View is to be Alphanumeric string
created from
Example
Public Sub Create()

Reporting.Explorations.create "http://computername", "Planning Sample",
"plan_BudgetPlan", "Goal Input"
End Sub
IBM API 137

CreateFromMDX
CreateFromMDX generates an Exploration View based on the host system URL, server name, and MDX string.
Syntax
Reporting.Explorations.CreateFromMDX “<host system URL>”, “<server name>”, “<MDX>”
Parameters
Table 19: Arguments for CreateFromMDX

host system URL URL of the host system which the Exploration View is Alphanumeric string
to be created from
server name Name of the server which the Exploration View is to be Alphanumeric string
created from
MDX MDX statement which the Exploration View is to be Alphanumeric string
created from
Example
Public Sub CreateFromMDX()

Reporting.Explorations.CreateFromMDX "http://vottepps06.canlab.ibm.com:9510/",
"Planning Sample", "SELECT {[plan_chart_of_accounts].[plan_chart_of_accounts].
[Revenue]} ON 0, {[plan_time].[plan_time].[2004]} ON 1 FROM [plan_BudgetPlan]"
End Sub
GetColumnSuppression
GetColumnSuppression is used to return whether or not zero-suppression is applied to columns in the exploration.
Syntax
Reporting.Explorations.GetAt().GetColumnSuppression
Example
Public Sub AreColumnsSuppressed()

MsgBox Reporting.Explorations.GetAt(Application.ActiveSheet.Name).
GetColumnSuppression
End Sub
GetRowSuppression
GetRowSuppression is used to return whether or not zero-suppression is applied to rows in the exploration.
Syntax
Reporting.Explorations.GetAt().GetRowSuppression
Example
Public Sub AreRowsSuppressed()

MsgBox Reporting.Explorations.GetAt(Application.ActiveSheet.Name).
GetRowSuppression
End Sub
GetValue
GetValue is used to retrieve the value of a particular setting in a session.
Syntax
Reporting.Settings.GetValue("<Setting>")
Parameters
Table 20: Arguments for GetValue

Setting The name of the setting whose value you want to String
retrieve.
Example
The following is an example using the syntax:
Public Sub ToggleSetEditorPreview()

Dim x
x = Reporting.Settings.GetValue("SetEditorPreviewOn")
If "True" = x Then
Reporting.Settings.SetValue "SetEditorPreviewOn", "False"
Else
Reporting.Settings.SetValue "SetEditorPreviewOn", "True"
End If
End Sub
Refresh
Refresh is used to refresh the exploration.
Syntax
Reporting.Explorations.GetAt().Refresh
Example
Public Sub Refresh()

Reporting.Explorations.GetAt(Application.ActiveSheet.Name).Refresh
End Sub
SwapRowsAndColumns
SwapRowsAndColumns is used to swap the rows and columns in an exploration.
Syntax
Reporting.Explorations.GetAt().SwapRowsAndColumns
Example
IBM API 139

Public Sub SwapsRowsAndColumns()

Reporting.Explorations.GetAt(Application.ActiveSheet.Name).SwapsRowsAndColumns
End Sub
SetRowSuppression
SetRowSuppression is used to enable and disable zero-suppression for rows in an exploration.
Syntax
Reporting.Explorations.GetAt().SetRowSuppression <True/False value>
Parameters
Table 21: Arguments for SetRowSuppression

True Enables zero-suppression Boolean
False Disables zero-suppression Boolean
Example
Public Sub SetRowSuppressions()

Reporting.Explorations.GetAt(Application.ActiveSheet.Name).SetRowSuppression
True
End Sub
SetColumnSuppression
SetColumnSuppression is used to enable and disable zero-suppression for columns in an exploration.
Syntax
Reporting.Explorations.GetAt().SetColumnSuppression <True/False value>
Parameters
Table 22: Arguments for SetColumnSuppression

True Enables zero-suppression Boolean
False Disables zero-suppression Boolean
Example
Public Sub SetColumnSuppressions()

Reporting.Explorations.GetAt(Application.ActiveSheet.Name).SetColumnSuppression
True
End Sub
Unlink
Unlink is used to convert an exploration to a static worksheet.
Syntax
Reporting.Explorations.GetAt().Unlink
Example
Public Sub Unlink()

Reporting.Explorations.GetAt(Application.ActiveSheet.Name).Unlink
End Sub
SetSpecification
SetSpecification is used to define the subset and dimension properties of an existing exploration.
Syntax
Reporting.Explorations.GetAt().SetSpecification “<MDX>”
Parameters
Table 23: Arguments for SetSpecification

MDX MDX statement used to define the subset and String

dimension properties of the exploration.
Example
Public Sub SetSpecifications()

Reporting.Explorations.GetAt(Application.ActiveSheet.Name).SetSpecification
"SELECT TM1SubsetToSet([plan_time], ""current_year_and_qtrs"") DIMENSION
PROPERTIES MEMBER_UNIQUE_NAME, MEMBER_NAME, MEMBER_CAPTION, LEVEL_NUMBER,
CHILDREN_CARDINALITY, [plan_time].[Time] ON 0, TM1TOGGLEDRILLSTATE
(TM1SubsetToSet([plan_chart_of_accounts], ""Default"") ,
{[plan_chart_of_accounts].[Revenue],[plan_chart_of_accounts].
[Operating Expense]} , EXPAND_BELOW , RECURSIVE) DIMENSION PROPERTIES
MEMBER_UNIQUE_NAME, MEMBER_NAME, MEMBER_CAPTION, LEVEL_NUMBER,
CHILDREN_CARDINALITY, [plan_chart_of_accounts].[AccountName] ON 1 FROM
[plan_BudgetPlan] WHERE ([plan_version].[FY 2004 Budget] ,
[plan_business_unit].[10000] , [plan_department].[1000] ,
[plan_exchange_rates].[actual] , [plan_source].[goal]) DIMENSION PROPERTIES
MEMBER_UNIQUE_NAME, MEMBER_NAME, MEMBER_CAPTION, LEVEL_NUMBER,
CHILDREN_CARDINALITY , [plan_version].[VersionName] , [plan_business_unit].
[BusinessUnit] , [plan_department].[Department] , [plan_source].[Source]"
End Sub
SetValue
SetValue is used to set a new value for a specific setting and save the changes to the settings file.
Syntax
Reporting.Settings.SetValue "<Setting>", "<Value>"
IBM API 141

Parameters
Table 24: Arguments for SetValue

Setting The name of the setting whose value you want to set. String
Value The boolean value you want to set for the specified True/False boolean
setting.
Example
The following is an example using the syntax:
Public Sub ToggleSetEditorPreview()

Dim x
x = Reporting.Settings.GetValue("SetEditorPreviewOn")
If "True" = x Then
Reporting.Settings.SetValue "SetEditorPreviewOn", "False"
Else
Reporting.Settings.SetValue "SetEditorPreviewOn", "True"
End If
End Sub
Quick Report API functions

Quick Report functions can be used to interact with Quick Report worksheets.
The Quick Report functions that are exposed through the IBM Cognos automation objects are:
Clear
Clear is used to clear data from the Quick Report.
Syntax
Reporting.GetCurrentReport().Clear
Example
Public Sub Clear()

Reporting.GetCurrentReport(ActiveCell).Clear
End Sub
ColumnHierarchies
ColumnHierarchies is used to return the hierarchies that exist in the columns of a Quick Report report.
Syntax
cafe.QuickReports.Get("<Quick Report ID").ColumnDimensions
Parameters
Table 25: Arguments for ColumnHierarchies

Quick Report ID The ID of the Quick Report that the column hierarchies Integer
are being returned from
Example
Sub ColumnHierarchies()
Dim columns As String
For Each Column In cafe.QuickReports.Get("0").ColumnDimensions
If columns <> "" Then
columns = columns & ", " & vbNewLine
End If
columns = columns & Column
MsgBox "Columns:" columns
End Sub
Commit
Commit is used to commit the Quick Report report.
Syntax
Reporting.GetCurrentReport().Commit <True>
Example
Public Sub Commit()

Reporting.GetCurrentReport(ActiveCell).Commit True
End Sub
Create
Create generates a Quick Report based on the host system URL, server name, cube name, and view name.
Syntax
Reporting.QuickReports.Create "<host system URL>", "<server name>", "<cube name>",

"<view name>"
Parameters
Table 26: Arguments for Create

host system URL URL of the host system which the Quick Report is to be Alphanumeric string
created from
server name Name of the server which the Quick Report is to be Alphanumeric string
created from
IBM API 143

Table 26: Arguments for Create (continued)
cube name Name of the cube which the Quick Report is to be Alphanumeric string
created from
view name Name of the view which the Quick Report is to be Alphanumeric string
created from
Example
Public Sub Create()

Reporting.QuickReports.Create "http://computername/", "Planning Sample",
"plan_BudgetPlan", "Goal Input"
End Sub
CreateFromMDX
CreateFromMDX generates a Quick Report based on the host system URL, server name, and MDX string.
Syntax
Reporting.QuickReports.CreateFromMDX “<host system URL>”, “<server name>”, “<MDX>”
Parameters
Table 27: Arguments for CreateFromMDX

host system URL URL of the host system which the Quick Report is to be Alphanumeric string
created from
server name Name of the server which the Quick Report is to be Alphanumeric string
created from
MDX MDX statement which the Quick Report is to be created Alphanumeric string
from
Example
Public Sub CreateFromMDX()

Reporting.QuickReports.CreateFromMDX "http://vottepps06.canlab.ibm.com:9510/",
"Planning Sample", "SELECT {[plan_chart_of_accounts].[plan_chart_of_accounts].
[Revenue]} ON 0, {[plan_time].[plan_time].[2004]} ON 1 FROM [plan_BudgetPlan]"
End Sub
Cube
Cube returns the search path of the Quick Report. For example, if the Quick Report is located in the plan_BudgetPlan
cube, in the Planning Sample server, the Cube function would return:
“{“server”:Planning Sample, “cube”:plan_BudgetPlan}”
Syntax
Reporting.GetCurrentReport().Cube
Example
Public Sub Cube()

MsgBox Reporting.GetCurrentReport(ActiveCell).Cube
End Sub
DataSource
DataSource is used to return the Quick Report host URL.
Syntax
Reporting.GetCurrentReport().DataSource
Example
Public Sub DataSource()

MsgBox Reporting.GetCurrentReport(ActiveCell).DataSource
End Sub
EnableIndents
EnableIndents is used to enable level based indents in your Quick Report reports.
Syntax
Reporting.GetCurrentReport().EnableIndents <True/False value>
Parameters
Table 28: Arguments for EnableIndents

True Enables indents in Quick Reports Boolean
False Disables indents in Quick Reports Boolean
Example The following syntax is an example:
Public Sub EnableIndents()

Reporting.GetCurrentReport(ActiveCell).EnableIndents True
End Sub
GetTuple
GetTuple is used to return the tuple of a Quick Report at a given range. This function will return the tuple at the
ActiveCell if no range is specified.
Syntax
cafe.QuickReports.Get("<Quick Report ID>").GetTuple(ActiveCell)
IBM API 145

Parameters
Table 29: Arguments for GetTuple

Quick Report ID The ID of the Quick Report that the tuple is being Integer
returned from.
Example
Sub PrintTuple()
Set tupleObject = cafe.QuickReports.Get("0").GetTuple(ActiveCell)
Dim tuple As String
For tupleIdx = 0 To tupleObject.Count - 1
If tuple <> "" Then
tuple = tuple & ", " & vbNewLine
End If
tuple = tuple & tupleObject.Item(tupleIdx)
Next
MsgBox "Tuple: " & vbNewLine & tuple
End Sub
GetSpecification
GetSpecification is used to return the MDX string that is used to build the current Quick Report.
Syntax
Reporting.GetCurrentReport().GetSpecification
Example
Public Sub GetSpecification()

MsgBox Reporting.GetCurrentReport(ActiveCell).GetSpecification
End Sub
GetReport
GetReport is used to return a specific Quick Report based on the Quick Report ID.
Syntax
Reporting.QuickReports.Get ("<report ID>")
Parameters
Table 30: Arguments for GetReport

report ID ID of the Quick Report which the function is to return Integer
Example
Public Sub GetReport()

Reporting.QuickReports.Get ("5")
End Sub
ID
ID is used to return the Quick Report ID.
Syntax
Reporting.GetCurrentReport().ID
Example
Public Sub ID()

MsgBox Reporting.GetCurrentReport(ActiveCell).ID
End Sub
Name
Name is used to return the cube name and view name which the Quick Report is created from.
Syntax
Reporting.GetCurrentReport().Name
Example
Public Sub Name()

MsgBox Reporting.GetCurrentReport(ActiveCell).Name
End Sub
RebuildSpecification
RebuildSpecification is used to return the MDX string that is used when rebuilding the Quick Report.
Syntax
Reporting.GetCurrentReport().RebuildSpecification
Example
The following syntax is an example:=
Public Sub RebuildSpecification()

MsgBox Reporting.GetCurrentReport(ActiveCell).RebuildSpecification
End Sub
Rebuild
Rebuild is used to rebuild a Quick Report.
Syntax
Reporting.GetCurrentReport().Rebuild
Example
IBM API 147

Public Sub Rebuild()

Reporting.GetCurrentReport(ActiveCell).Rebuild
End Sub
Refresh
Refresh is used to refresh a Quick Report.
Syntax
Reporting.GetCurrentReport().Refresh
Example
Public Sub Refresh()

Reporting.GetCurrentReport(ActiveCell).Refresh
End Sub
Replace
Replace is used to replace the MDX statement in the Quick Report with another MDX statement.
Syntax
Reporting.QuickReports.Replace Reporting.GetCurrentReport(ActiveCell).<Quick Report ID>,
<MDX statement>
Table 31: Arguments for Replace

Quick Report ID The ID of the Quick Report that will have its MDX Integer
statement replaced
MDX statement The MDX statement that will be replacing the current String
MDX statement in the Quick Report
Example
Public Sub Replace()

Reporting.QuickReports.Replace Reporting.GetCurrentReport(ActiveCell).4,
"SELECT {[plan_chart_of_accounts].[plan_chart_of_accounts].[Revenue]} ON 0,
{[plan_time].[plan_time].[2004]} ON 1 FROM [plan_BudgetPlan]"
End Sub
RowHierarchies
RowHierarchies is used to return the hierarchies that exist in the rows of a Quick Report.
Syntax
cafe.QuickReports.Get("<Quick Report ID").RowDimensions
Parameters
Table 32: Arguments for RowHierarchies

Quick Report ID The ID of the Quick Report that the row hierarchies are Integer
being returned from
Example
Sub RowHierarchies()
Dim slicers As String
For Each Slicer In cafe.QuickReports.Get("0").SlicerDimensions
If slicers <> "" Then
slicers = slicers & ", " & vbNewLine
End If
slicers = slicers & Slicer
Next
MsgBox "Rows:" rows
End Sub
Select
Select is used to select and highlight the current active Quick Report.
Syntax
Reporting.GetCurrentReport().Select
Example
Public Sub SelectReport()

Reporting.GetCurrentReport(ActiveCell).Select
End Sub
SetSlicer
SetSlicer is used to set the values for a slicer dimension in the Quick Report.
Syntax
Reporting.GetCurrentReport().SetSlicer “<dimensions>, <name>”
Parameters
Table 33: Arguments for SetSlicer

dimensions The dimensions to set the slicer to String
name The name to set the slicer to String
Example
IBM API 149

Public Sub SetSlicer()

Reporting.GetCurrentReport(ActiveCell).SetSlicer "[plan_business_unit].
[plan_business_unit]", "10100"
End Sub
SlicerHierarchies
SlicerHierarchies is used to return the hierarchies that exist in the slicers of a Quick Report.
Syntax
cafe.QuickReports.Get("<Quick Report ID").SlicerDimensions
Parameters
Table 34: Arguments for SlicerHierarchies

Quick Report ID The ID of the Quick Report that the slicer hierarchies Integer
are being returned from
Example
Sub RowHierarchies()
Dim slicers As String
For Each Slicer In cafe.QuickReports.Get("0").SlicerDimensions
If slicers <> "" Then
slicers = slicers & ", " & vbNewLine
End If
slicers = slicers & Slicer
Next
MsgBox "Slicers:" slicers
End Sub
Dynamic Report API functions

Dynamic Report functions can be used to interact with Dynamic Report worksheets.
The Dynamic Report functions that are exposed through the IBM Cognos automation objects are
Refresh
This API call is used to refresh a Dynamic Report.
Syntax
Reporting.DynamicReports.GetAt().Item(<Dynamic Report ID>).Refresh
Parameters
Table 35: Arguments for Refresh

Dynamic Report ID The ID of the Dynamic Report that is to be refreshed Integer
Example
Reporting.DynamicReports.GetAt(DynamicReports.Worksheet.Name).Item(0).Refresh
Rebuild
This API call is used to rebuild a Dynamic Report.
Syntax
Reporting.DynamicReports.GetAt().Item(<Dynamic Report ID>).Rebuild
Parameters
Table 36: Arguments for Rebuild

Dynamic Report ID The ID of the Dynamic Report that is to be rebuilt Integer
Example
Reporting.DynamicReports.GetAt(ActiveCell.Worksheet.Name).Item(0).Rebuild
Example - processing within VBA

The following example demonstrates how to call the Logon method within VBA:
("http://localhost/ibmcognos/cgi-bin/cognos.cgi","Administrator",
"CognosAdmin", "Production")
If bResult Then
CognosOfficeAutomationObject.ClearAllData()
CognosOfficeAutomationObject.RefreshAllData()
CognosOfficeAutomationObject.Logoff()
Dim sTraceLog as String
sTraceLog = CognosOfficeAutomationObject.TraceLog
'Here is where you could write the trace log to file.
MsgBox sTraceLog
End If
Macro files
IBM API 151

The macro files for Cognos Office are written in Microsoft Visual Basic for Applications (VBA).
The files are installed with IBM Cognos Office in the automation folder. The default location is
[installation_directory]\Automation.
The following macro files are installed.
Table 37: Sample macros
File Description
CognosOfficeAutomationExample.bas Because it is a BASIC file created using VBA, this file has the
extension .bas. It contains the
CognosOfficeAutomationObject property that enables IBM
Cognos Office automation in the current document. It also
contains wrapper functions that call the API exposed by IBM
Cognos Office.
CognosOfficeMessageSuppressor.cls This file shows how to use the SuppressMessages API

function.
Script files
The installation includes sample script files that you can use to automate functions. The samples include script files for
scheduling the refresh of documents. Also, there is a script file to update the server URL.
You must modify the script files to meet your particular needs or use them as a reference to create your own programs.
For more information, see the comments in the file.
These Visual Basic Scripts (VBS) are provided as sample programs and are located in installation_directory
\Automation:
• Automate_COI.vbs
• Automate_COI_Excel.vbs
• AutomateServerURLSample.vbs
Chapter 9. Tutorials
Getting started in Planning Analytics for Microsoft Excel is easy. Going through these tutorials will help you make sense
of the features that are offered in Planning Analytics for Microsoft Excel and how you might use them in your work.
In this tutorial, you are a new hire and you're just starting your job as a business analyst at an automotive company.
Your position requires you to analyze existing data, edit reports and create new reports by using Planning Analytics for
Microsoft Excel. You are familiar with Microsoft Excel, but you never used Planning Analytics for Microsoft Excel before
and have little data modeling knowledge. This series of tutorials will guide you through the basics of Planning Analytics
for Microsoft Excel and help to on your way to becoming a star business analyst.
Get started
You sit down at your desk with your morning coffee. You're the new business analyst. Excited to make a good first
impression, you immediately turn on your computer and open Microsoft Excel; the emails from Mom can wait. The user
interface is familiar but there's a new tab. Let's get started.
Procedure
1. Open Microsoft Excel.
2. Click the IBM Planning Analytics tab.
The Planning Analytics for Microsoft Excel ribbon displays commands for starting Planning Analytics for Microsoft
Excel, logging on to IBM TM1 systems, setting options, opening reports that are published to an IBM TM1 server,
and so on. Report-specific sections might appear here as well when you're working in them.
What to do next
It is difficult to analyze data and create reports when you have no data to analyze. Continue by adding a system with
data sources to connect to.
How do I add a system?

To get started with Planning Analytics for Microsoft Excel, you need to add a system and connect to a data source. The
data source is where the data you'll be importing to analyze will come from.
Procedure
1. Click Connect.

2. Click New Connection .
Unless a data source was already configured by your administrator, you need to add a data source before you can
connect to one.
3. Define the Datasource type , the Connection URL, and a Friendly name to help you easily remember what your
data sources are for.
If you're not sure of the Datasource type and Connection URL, ask your administrator.
4. Click Test connection .
This step ensures that the connection to the data source is accurate and live.
5. Click Save .
How do I connect to a data source?

Now that you have your connection set up, it's time to connect to a data source.
Procedure
1. Click Connect.
2. Hover your cursor over the connection.
3. Click SDataHierarchies.
4. Log in to the data source by using your credentials.
Results
You are now connected to a data source and the IBM task pane is opened on the right of the screen.
The IBM task pane opens when you connect to a data source in Planning Analytics for Microsoft Excel. The IBM task
pane is where your workbooks are organized and where you can find a tree for all of your views, cubes, dimensions,
measures, and members. If you're unfamiliar with these terms, watch this video on the basics to modeling and
modeling concepts:
https://youtu.be/uXrE05A4QFc
You can change the position of the IBM task pane by clicking near the top of the task pane and dragging it to another
area on the screen.
Tutorials 155
First assignment
You receive an email from your manager. It's your first assignment!
Hi newbie,
Welcome to the team! As you know, this company sells vehicles world-wide. We are
currently reviewing our sales for 2014. Please send a report that shows the following:
- Only sales for convertibles and sedans
- Only sales in Europe
- Only the actuals
- The quarters in the columns
- Data from 2014
You can find the data you need in the SDataHierarchies data source. You can log into
this data source using the following credentials:
username:
password:
Regards,
Your manager
So now that you have your assignment, it's time to get to work.
You can also follow along by watching this video: https://youtu.be/4ELlqhqtJjc
Views
How do I check for existing views?

You have your first assignment. Your manager asked you to check for a report that analyzes sales in 2014. Start by
checking whether such a view already exists.
Procedure
1. The top of the IBM task pane contains two tabs; SDataHierarchies and Workbook. Click the Workbook tab.
The Workbook tab shows all of the Dynamic reports, Action buttons, Explorations, and Quick reports that you have
in your workbook. As you can see, no reports are currently in your workbook. No problem, you can create one
yourself.
2. Click the SDataHierarchies tab.
That's a lot of content. The cube icon indicates that the item is a cube, and the dimension icon indicates that
the item is a dimension. Notice that there's a cube that is named "WorldSales". That looks like it might have what
you need.
What to do next
Impress your manager by creating an Exploration View from the 2014F view.
How do I create a new view?
Procedure
1. Expand WorldSales.
Notice that there's a new type of icon. This icon is the views icon . This item contains views that are in this
particular cube. You want to see whether there's already an existing view that has the report you're looking for.
2. Expand Views.
Another new type of icon! This is the icon for individual views . If you expand an individual view, you can see the
content inside of the view. The 2014F view looks like it's just what you need. Now how do you create a report from
it?
3. Drag 2014F and drop it into the workspace area.
Dragging a view into the workspace area creates a list view.
Results
Congratulations on creating your first list view. List views are good for showing data with little formatting. List views are
good for simple analyzes with simple data. But you didn't get hired for simple reports. And you sure aren't going to
show a list view to your manager as your first report! You're going to re-create this report as an Exploration View.
Can I create an Exploration View from an existing view?

Exploration views are great for exploring data in a pivot table style format. They're easy to manipulate and can be
changed dynamically.
In the last tutorial, you created a list view. But you want something more powerful. Something that more closely
resembles a pivot table. The Exploration View is perfect for that.
Procedure
1. Under the SDataHierarchies tab, expand WorldSales > Views.
Tutorials 157
2. Right-click 2014F.
3. Hover your cursor over Exploration view.
4. Click On new sheet.
Results
An Exploration View is created from the 2014F view.
What to do next
Your Exploration View is great, but it does not meet the requirements from your manager. Next, you will customize the
Exploration View to meet your manager's needs.
Customize Exploration Views

Exploration Views are flexible reports. Exploration Views allow for exploring data in a pivot style format. Perfect for
quickly customizing your Exploration View for the manager.
Have a look at the Exploration View you created from the 2014F view. It is huge. Scroll down the report and you see
that the report contains a number of things that your manager did not ask for: sales for wagons, the budget, sales for
Canada, and so on. A summary of the report's content is presented in the overview bar below the ribbon:
The rows drop zone contains sets that are found in the rows of the Exploration View. The columns drop zone
contains sets that are found in the columns of the Exploration View. The context drop zone contains sets that make
up the context of the report. From the overview bar, you can edit the sets that are contained in the Exploration View.
How do I insert and replace members into a set?

Your Exploration Views looks great, but it shows all model types instead of just convertibles and sedans. Change that
now by inserting and replacing members in the model set.
Procedure
1. Right-click the model set in the rows drop zone.
2. Click Edit Set.
The set editor opens for the model set. You use the set editor to customize which members are displayed in your
Exploration View.
Note: Your manager wants to see data for convertibles and sedans.
3. Input convertible in the search bar and then press enter.
The search results now contains only members with the word convertible in their names.
4. Click Search - (Name Contains convertible)

This member contains every search result member and dynamically updates if the set changes.
5. Click the replace set icon .

The replace set icon replaces the entire current set with the member that you selected from the available members
section.
6. Input sedan in the search bar and then press enter.
The search results now contains only members with the word sedan in their names.
Tutorials 159
7. Click Search - (Name Contains sedan)
8. Click the insert icon
The insert icon inserts the selected members into the current set.
Results
Your Exploration View contains only data for convertibles and sedans.
What to do next
Your Exploration View contains data for the actuals and the budget. Your manager wants to see data for the actuals. In
the next tutorial, you will be removing a member from the set editor.
How do I remove members from a set?
Your manager wants to see just the data for the actuals, but your Exploration Views contains both the actuals and the
budget. You need to remove the budget member from the Version set in the set editor.
Procedure
1. Right-click the Version set in the rows drop zone.
2. Click Edit Set.
3. Right-click Budget under Current Set
4. Click Remove.
Results
Your Exploration View contains only data for the actuals.
What to do next
Your Exploration Views looks good, but you still need to show only Europe. In the next tutorial, you will be expanding a
set to show specific levels in a set.
How do I expand levels in a set?

Your Exploration Views contains both the actuals and the budget. Remove the budget member from the Version set in
the set editor.
Procedure
1. Right-click the regions set in the rows drop zone.
2. Click Edit Set.
3. Expand the World member under Available Members.

4. Click Europe.
Tutorials 161
6. Click Apply and close .

7. Right-click any Europe cells in the workspace.
8. Click IBM Planning Analytics .
9. Click Expand / Collapse .
Results
Your Exploration View shows data for only the Europe member with the member expanded.
What to do next
Your Exploration Views is almost complete. Next, add quarters to the columns.
How do I use the drop zones?
Your Exploration Views is almost complete. Add the quarters for 2014 to the columns.
Procedure
1. Drag the Time set from the context drop zone into the columns drop zone.
2. Right-click the Time set.

3. Click Edit Set.
4. Expand 2014 from the Available Members section.
5. Select 2014 - Q1, 2014 - Q2, 2014 - Q3, 2014 - Q4.
7. Click Apply and close .
Results
Your Exploration View contains the quarters for 2014 in the columns.
What to do next
Your Exploration Views is complete.
Share your work
About this task

Now that you have your first report created, it is time to share it with your manager. You can either save the workbook
as an Excel file and send that, or you can publish it to the server you are connected to.
How do I share my report by publishing it to the server?
About this task

Publishing your reports to a server is easy and is a great way to share your analysis with colleagues!
Procedure
1. Click Publish.
2. Select a TM1 connection.
Tutorials 163
3. Select a TM1 Server Application folder.
4. Select a folder.
5. Type a name for the workbook.
6. Select Make public
7. Click Publish.
Results
Your workbook is ready to be shared with your manager and colleagues. They can view the workbook and contribute to
it as well.
Chapter 10. Examples and use cases
Using IBM Planning Analytics for Microsoft Excel you can create an Exploration View. Use Exploration Views to show
information in a more compact form than in a grouped list. For example, create an Exploration View to show total sales
by product line generated by each sales representative.
Like list reports, Exploration Views are reports that show data in rows and columns. However, the values at the
intersection points of rows and columns show summarized information rather than detailed information.
You can also create list reports from relational data sources.
Work with items in an Exploration View

You can manipulate the way rows and columns appear in an Exploration View for more effective comparison.
You can do this by
• nesting rows or columns Nest rows or columns
• swapping rows and columns “Swap rows and columns” on page 45
• showing or hiding rows or columns Limit items
Exploration is a process in which you explore the relationships between items to help understand your business. The
Exploration View helps you discover whether the value of one item is associated with that of another.
Comparisons are key elements of nearly every exploration. The following table shows examples of different types of
comparisons.
Table 38: Examples of comparisons

Comparison Example
Simple comparison Tents versus sleeping bags
Multiple comparison Tents versus golf clubs, tees, and golf balls
Multidimensional comparison Products versus territories, this year-to-date versus last
year-to-date
Mixed comparison Tents versus similar camping products, this year versus last
year, and the last quarter versus last year
Summaries of measures at different levels Tents as a share of camping products, as a share of European
sales
Explorations and relational sources

Explorations can be used to transform relational sources into an Exploration View that allows dimensional style layout.
Filters for relational explorations are, however, detail filters as opposed to dimensional. If dimensional style layout and
filtering are common requirements, we recommend that you create a DMR model for this data source to simplify report
creation.
Explorations and dimensional sources

We recommend that you use explorations for dimensional sources. Even if the report has a simple layout with no
nesting and measures as columns, the query supports precise filtering if created as an Exploration View.
Work with relational Exploration Views

Relational data in Exploration Views has limitations and differences from dimensional data. One such instance is
replacing measures on columns. Measures derived from relational data are stacked blocks. Replacement of the entire
stacked block on the grid is not permitted. You would need to do this on the summary bar. This behavior is consistent

with query items that are not measures. You may also notice that expand, collapse and totals do not work with
relational data sources.
Sets
Sets are the basic building blocks of IBM Planning Analytics for Microsoft Excel. A set identifies a group of items from a
single hierarchy. You can manipulate the individual sets in the Exploration View.
Sets may be
• nested or stacked in the Exploration View
• used as filters
The following list describes the different kinds of sets you can use.
Simple
A single member and its direct dependents one level down.
Selection-based set
A collection of individual items that you have explicitly selected. The items or members may be selected from one
or more levels from the same hierarchy and are not aggregated.
Combination set
A set consisting of more than one simple or selection-based set.
Nest columns or rows in an Exploration View

Nest data in an Exploration View to compare information by using more than one data item in a column or row. For
example, an Exploration View shows the number of sales by product line for the past fiscal year. You decide to add a
data item to further break down the number of sales by quarter.
When nesting columns in an Exploration View, there are four distinct drop zones where you can insert a new data item.
The drop zone you choose defines the relationship between the data item and the column.
The following relationships are created when you insert a data item as a row:
• Inserting a data item before or after a column creates a parent-child relationship between the data items.
When you insert a data item before a column, the data item becomes a parent to the row. When you insert a data item
after a column, the data item becomes a child of the row.
• Inserting a data item before or after a column creates a union relationship between the data items.
The following relationships are created when you insert a data item as a column:
• Inserting a data item before or after a column creates a union relationship between the data item and the column.
• Inserting a data item before or after a row creates a parent-child relationship between the data items.
When you insert a data item before a column, the data item becomes a parent to the column. When you insert a data
item after a column, the data item becomes a child of the column.
For example, you have an Exploration View with Product line as rows and Quantity and Revenue as nested rows. For
columns, you have Order method with Country or Region as a nested column.
• Product line is a parent to Quantity and Revenue.
• Quantity and Revenue are peers.
• Order method is a parent to Country or Region.
Procedure
1. In the source tree, click the data item you want to add to the report.
2. Drag the data item to the location where you want it to appear as a nested column or nested row.
A highlight bar indicates where you can drop the data item.
3. Repeat step 2 to add other nested columns or rows.
Tip: If you add more than one measure to an Exploration View to the same axis, you must add them as a set. Ctrl
+click the items or, to add a measure to another measure already in the Exploration View, press the Ctrl key while
dragging the item to the other measure.
Example - evaluate revenue from specific order methods
You are a business analyst at the Sample Outdoors Company, which sells sporting equipment. You are asked to analyze
the consequences of discontinuing the fax and mail order methods, which are expensive to process.
First you get the items you need and insert them into an Exploration View for further exploration.
Before you can try this example, you must have access to the sample packages that come with IBM Cognos Analytics.
For more information, see the IBM Cognos Analytics Administration and Security Guide.
Procedure
1. In Microsoft Excel, click the IBM Planning Analytics tab.
2. To connect to the IBM Cognos Analytics system to access the sample package, click Connect and select the server.
3. Select the Sales and Marketing package and click OK.
4. Expand the Order Method folder.
5. Press Ctrl and click Fax and Mail.
6. With Fax and Mail selected, right-click Mail and click New Set.
7. In the Selection on Dimension dialog box, click Save and save the set using the default name, Order method.
8. On the IBM Planning Analytics tab, click Exploration.
9. Expand the Custom Sets folder and drag the Order method set to the Rows area in the Exploration View.
10.Expand the Sales measures folder and drag Revenue to the Measure area in the Exploration View.
11.Drag Retailers to the Columns area in the Exploration View.
12.Expand the Time folder and drag Time beside the order methods to nest years in the rows.
Results
You now have the data required to analyze if revenues for the fax and mail order methods are growing or declining over
time.
Examples and use cases 167

Figure 9: Exploration View
Work with items in a list

Use lists to show detailed information from your database, such as customer lists or product lists.
A list is a report that shows data in rows and columns. Each column shows all the values for a data item in the database
or a calculation based on data items in the database. Lists are useful for very large reports that require minimal
filtering.
Lists and relational sources

Use lists for relational sources.
Lists and dimensional sources

Avoid using lists with dimensional sources. It is preferable to use Exploration Views with dimensional sources
whenever possible, because it will provide much richer filtering capability. However, lists are useful against dimensional
sources if there is no measure in the report. Such a report cannot be created as an Exploration View and can only be
created as a list.
Example - create a list report

In this topic, you will use the GO Data Warehouse model. It contains data about human resources, sales and marketing,
and finance, grouped into business areas.
You will learn how to
• create a list report
The report shows revenue for each product for the last quarter of the current year.
• group items in the list report
You group data items in a list report to remove duplicate values. For example, you have a report that shows products
purchased. For each product, the product type is also shown. You group the Product type column to show only one
instance of each product type in the list.
Procedure
1. Open the GO Data Warehouse (query) package.
2. On the IBM Planning Analytics, click List.
3. Expand Sales and Marketing (query), Sales (query) and then drag items to the worksheet to create the report.
You can also add an item to the report by selecting the item, opening the item's context menu, and selecting Add to
columns.
• Expand Products and drag Product type to the drop zone.
• Expand Time dimension, and drag Quarter beside Product type.
• Expand Sales orders, and drag Order number beside Quarter.
• Expand Product, and drag Product name beside Order number.
• Expand Sales fact, and drag Quantity beside Product name.
• From Sales fact, drag Unit cost beside Quantity.
4. Create the calculation Quantity * Unit price.
5. Rename the calculation to Revenue.
6. Group the Product type column and then group the Quarter column.
Results
Your report will look like the following:
Figure 10: List report
If you need more help, see the following:
Examples and use cases 169

• “Exploration Views and lists” on page 39
• Nest rows or columns
Chapter 11. Troubleshoot
Use this troubleshooting reference information as a resource to help you solve specific problems you may encounter
during or after the installation of IBM Planning Analytics for Microsoft Excel.
Troubleshoot a problem
Troubleshooting is a systematic approach to solving a problem. The goal of troubleshooting is to determine why
something does not work as expected and how to resolve the problem.
The first step in the troubleshooting process is to describe the problem completely. Problem descriptions help you and
the IBM technical-support representative know where to start to find the cause of the problem. This step includes
asking yourself basic questions:
• What are the symptoms of the problem?
• Where does the problem occur?
• When does the problem occur?
• Under which conditions does the problem occur?
• Can the problem be reproduced?
The answers to these questions typically lead to a good description of the problem, which can then lead to a resolution
of the problem.
What are the symptoms of the problem?

When starting to describe a problem, the most obvious question is "What is the problem?" This question might seem
straightforward; however, you can break it down into several focused questions that create a more descriptive picture
of the problem. These questions can include:
• Who, or what, is reporting the problem?
• What are the error codes and messages?
• How does the system fail? For example, is the problem a loop, hang, crash, performance degradation, or incorrect
result?
Where does the problem occur?

Determining where the problem originates is not always easy, but it is one of the most important steps in resolving a
problem. Many layers of technology can exist between the reporting and failing components. Networks, disks, and
drivers are only a few of the components to consider when you are investigating problems.
The following questions help you to isolate the problem layer:
• Is the problem specific to one platform or operating system, or is it common across multiple platforms or operating
systems?
• Is the current environment and configuration supported?
If one layer reports the problem, the problem does not necessarily originate in that layer. Part of identifying where a
problem originates is understanding the environment in which it exists. Take some time to completely describe the
problem environment, including the operating system and version, all corresponding software and versions, and the
hardware. Confirm that you are running within an environment that is supported; many problems can be traced back to
incompatible levels of software that are not intended to run together or have not been fully tested together.
When does the problem occur?

Develop a detailed timeline of events leading up to a failure, especially for cases that are one-time occurrences. You
can most easily develop a timeline by working backward: Start at the time an error was reported (as precisely as
possible, even down to the millisecond), and work backward through the available logs and information. Typically, you
need to look only as far as the first suspicious event that you find in a diagnostic log.

To develop a detailed timeline of events, answer these questions:
• Does the problem happen only at a certain time of day or night?
• How often does the problem happen?
• What sequence of events leads up to the time that the problem is reported?
• Does the problem happen after an environment change, such as an upgrade or an installation of software or
hardware?
Under which conditions does the problem occur?

Knowing which systems and applications are running at the time that a problem occurs is an important part of
troubleshooting. These questions about your environment can help you to identify the cause of the problem:
• Does the problem always occur when the same task is being performed?
• Does a certain sequence of events need to occur for the problem to occur?
• Do any other applications fail at the same time?
Answering these types of questions can help you explain the environment in which the problem occurs and correlate
any dependencies. Remember that just because multiple problems might have occurred around the same time, the
problems are not necessarily related.
Can the problem be reproduced?

Problems that you can reproduce are often easier to solve. However, problems that you can reproduce can have a
disadvantage. If the problem as a significant business impact, you do not want it to recur. If possible, re-create the
problem in a test or development environment, which typically offers you more flexibility and control during your
investigation. Answer the following questions:
• Can the problem be re-created on a test system?
• Are multiple users or applications encountering the same type of problem?
• Can the problem be re-created by running a single command, a set of commands, or a particular application?
Get fixes
A product fix might be available to resolve your problem.
Procedure
To find and install fixes:
1. Determine which fix you need by using Fix Central (opens in new window) (http://www.ibm.com/support/fixcentral/)
2. Download the fix. Open the download document and follow the link in the "Download package" section.
3. Apply the fix by following the instructions in the "Installation Instructions" section of the download document.
4. Subscribe to receive weekly email notifications about fixes and other IBM Support information.
Contact IBM Support

IBM Support provides access to a variety of IBM resources for help with software questions.
Before you begin

After trying to find your answer or solution by using other self-help options such as technotes, you can contact IBM
Support. Before contacting IBM Support, your company must have an active IBM maintenance contract, and you must
be authorized to submit problems to IBM. You should also have the following information at hand:
• Your customer identification number
• Your service request number, if it is an ongoing service request
• The phone number where you can be reached
• The version of the software you use
• The version of the operating environment you use
• A description of what you were doing when the problem occurred
• The exact wording of any error messages that display
• Any steps you took to attempt to solve the problem
For information about the types of available support, see the Support portfolio topic in the Software Support Handbook
(opens in new window).
Procedure
Complete the following steps to contact IBM Support with a problem:
1. Define the problem, gather background information, and determine the severity of the problem. For more
information, see the Getting IBM support (opens in new window) topic in the Software Support Handbook.
2. Gather diagnostic information.
3. Submit the problem to IBM Support in one of the following ways:
• Using IBM Support Assistant (ISA): Use this feature to open, update, and view an Electronic Service Request with
IBM. Any data that has been collected can be attached to the service request. This expedites the analysis and
reduces the time to resolution.
• Online through the IBM Support Portal (opens in new window): You can open, update, and view all your Service
Requests from the Service Request portlet on the Service Request page.
• By phone: For the phone number to call, see the Directory of worldwide contacts (opens in new window) web
page.
Results
If the problem that you submit is for a software defect or for missing or inaccurate documentation, IBM Support
creates an Authorized Program Analysis Report (APAR). The APAR describes the problem in detail. Whenever possible,
IBM Support provides a workaround that you can implement until the APAR is resolved and a fix is delivered. IBM
publishes resolved APARs on the IBM Support Web site daily, so that other users who experience the same problem
can benefit from the same resolution.
Exchange information with IBM

To diagnose or identify a problem, you might need to provide IBM Support with data and information from your system.
In other cases, IBM Support might provide you with tools or utilities to use for problem determination.
Send information to IBM Support

To reduce the time that it takes to resolve your problem, you can send trace and diagnostic information to IBM Support.
Procedure
To submit diagnostic information to IBM Support:
1. Open a problem management record (PMR). You can use the IBM Support Assistant (opens in new window) or the
IBM Service Request tool (opens in new window).
2. Collect the diagnostic data that you need. Diagnostic data helps reduce the time that it takes to resolve your PMR.
You can collect the diagnostic data manually or automatically.
3. Compress the files by using the TRSMAIN or AMATERSE program. Download the free utility from the IBM web site to
the IBM Cognos system and then install the utility using the TSO RECEIVE command.
4. Transfer the files to IBM. You can use one of the following methods to transfer the files to IBM:
• The Service Request tool (opens in new window)
• Standard data upload methods: FTP, HTTP
• Secure data upload methods: FTPS, SFTP, HTTPS
• Email
Troubleshoot 173
If you are using an IBM Cognos product and you use ServiceLink / IBMLink to submit PMRs, you can send diagnostic
data to IBM Support in an email or by using FTP.
All of these data exchange methods are explained on the IBM Support site (opens in new window).
Receive information from IBM Support

Occasionally an IBM technical-support representative might ask you to download diagnostic tools or other files. You
can use FTP to download these files.
Before you begin

Ensure that your IBM technical-support representative provided you with the preferred server to use for downloading
the files and the exact directory and file names to access.
Procedure
To download files from IBM Support:
1. Use FTP to connect to the site that your IBM technical-support representative provided and log in as anonymous.
Use your email address as the password.
2. Change to the appropriate directory:
a) Change to the /fromibm directory.
cd fromibm
b) Change to the directory that your IBM technical-support representative provided.
cd nameofdirectory
3. Enable binary mode for your session.
binary
4. Use the get command to download the file that your IBM technical-support representative specified.
get filename.extension
5. End your FTP session.
quit
Subscribe to Support updates

To stay informed of important information about the IBM products that you use, you can subscribe to updates.
About this task

By subscribing to receive updates, you can receive important technical information and updates for specific Support
tools and resources. You can subscribe to updates by using one of two approaches:
RSS feeds and social media subscriptions
The following RSS feeds and social media subscriptions are available:
• RSS feed for the Support site for IBM Cognos Analysis for Microsoft Excel
• RSS feed for the Support site for IBM Cognos TM1
• RSS feed for a developerWorks® forum
For general information about RSS, including steps for getting started and a list of RSS-enabled IBM web pages,
visit the IBM Software Support RSS feeds (opens in new window) site.
My Notifications
With My Notifications, you can subscribe to Support updates for any IBM product. You can specify that you want to
receive daily or weekly email announcements. You can specify what type of information you want to receive, such
as publications, hints and tips, product flashes (also known as alerts), downloads, and drivers. My Notifications
enables you to customize and categorize the products that you want to be informed about and the delivery methods
that best suit your needs.
Procedure
To subscribe to Support updates:
1. Subscribe to the Product RSS feeds.
2. To subscribe to My Notifications, begin by going to the IBM Support Portal (opens in new window) and clicking My
Notifications in the Notifications portlet.
3. If you have already registered for My Support, sign in and skip to the next step. If you have not registered, click
Register now. Complete the registration form using your email address as your IBMid and click Submit.
4. Click Edit profile.
5. Click Add products and choose a product category; for example, Software.
6. In the second list, select a product segment; for example, Data & Information Management.
7. In the third list, select a product subsegment, for example, Databases.
8. Select the products that you want to receive updates for.
9. Click Add products.
10.After selecting all products that are of interest to you, click Subscribe to email on the Edit profile tab.
11.Select Please send these documents by weekly email.
12.Update your email address as needed.
13.In the Documents list, select the product category; for example, Software.
14.Select the types of documents that you want to receive information for.
15.Click Update.
Results
Until you modify your RSS feeds and My Notifications preferences, you receive notifications of updates that you have
requested. You can modify your preferences when needed (for example, if you stop using one product and begin using
another product).
Common errors
This section lists the most-common errors that you might encounter.
Configuration Issues
These issues are related to configuration and setup.
Convert to Formulas does not show value

You can create an Exploration View without experiencing an error, but when you convert that exploration sheet to
formulas, cells no longer display values properly. In one of the cells that has no value, you click the cell and it shows the
COGVAL formula, such as =COGVAL($C$1, $C$2, $B10, C$8, $B$8). Attempting to do this on another workstation you
find that values are displayed correctly. If a user with administrative rights to the workstation attempts to convert to
formulas, the values are displayed correctly in the cells of the worksheet.
The user did not use Microsoft Excel before IBM Planning Analytics for Microsoft Excel was installed and did not get
registered properly. There are two ways to resolve this problem. You can give the affected user local administration
rights to the workstation or you can run the file Register Cognos XLL.vbs, which will add the proper registry entries for
the new user.
For the Register Cognos XLL.vbs file process to work (both during the installation of the software or when run
separately to add a new user) the Microsoft Excel registry entries must have been created by Microsoft Excel itself. You
Troubleshoot 175
must ensure that the user run Microsoft Excel first, before attempting to add registry entries for IBM Planning Analytics
for Microsoft Excel. You can examine the ntuser.dat that the script writes to check whether the user has been properly
added.
The Cognos Office interface fails to initialize in Microsoft Office

IBM Cognos Office may not initialize when the Microsoft .NET Framework is not installed or the version is not correct.
The required Microsoft .NET Framework version is 4.6.1 or later. Another possible reason for this condition is that the
add-in is either not installed or not registered.
If you are running the wrong version of Microsoft .NET Framework, uninstall it and then reinstall Microsoft .NET
Framework.
To install the IBM Cognos add-in, run the installation program.
Before you attempt to install Microsoft .NET Programmability Support, you must have installed Microsoft .NET
Framework.
Microsoft Office does not open a Microsoft Office document published from Cognos Office
If you observe Microsoft Office trying to open a published document twice when you double-click the workbook,
document, or presentation from Microsoft Windows Explorer, the file association is either corrupted or not installed
properly.
There are two options to resolve this issue. You can start the Microsoft Office application first, and then open the
document using the Open command from the File menu, or you can reregister the file type.
Re-register file types with a Microsoft Office program
When you are not able to open a Microsoft Office document even though it is associated with the correct file type, you
must re-register the file type with the appropriate Microsoft Office program, such as Excel, Word, or PowerPoint.
About this task

In these steps, program.exe is a placeholder for the executable file for the Microsoft Office program that you want to
re-register. If you installed Microsoft Office to another location, use the path that is correct for that location.
Note: If you are using the command line on version 7 of Microsoft Windows operating system, you must elevate the
rights of the command line to perform certain tasks, such as re-registering file types. To open an elevated command
prompt, or a command prompt in Administrator mode, right-click the command prompt shortcut, and select Run as
Administrator.
Procedure
1. From the Start menu, click Run.
2. To disassociate the program version, in the Open box, type the following command, and then click OK:
program.exe/regserver
3. To specify the default version, from the Start menu, click Run.
4. In the Open box, type the following command, and then click OK:
program.exe/regserver
.NET Messages are not in the installed .NET Framework language

When you install a non-English version of .NET Framework in a non-English operating system, you will notice that the
error messages, .NET shortcut, and .NET Console are in English.
To solve this issue, you must apply the .NET Framework Language Pack for your language.
The subkey numbers relate to the language. For example, English, French, German, and Japanese are listed here:
1033=en-en, 1036=fr-fr, 1031=de-de, and 1041=ja. Refer to the Microsoft Support Site to obtain subkey numbers for
other languages.
If you are missing the language pack subkeys, you must install the .NET language pack, which is available from the
Microsoft support Web site.
Workbook closes unexpectedly
If you install the COM add-in and your Microsoft Excel workbook name contains a square bracket, Excel stops
responding or closes unexpectedly after opening.
To resolve this problem, rename the workbook so that it does not contain square brackets.
Processing issues
The following issues are related to processing and rendering reports.
Improve performance for TM1 data

If you experience unacceptable performance when you work with TM1 data, the administrator of the TM1 system might
be able to change cube or system settings to improve performance. To help the TM1 administrator evaluate the
performance issue, provide the administrator with the details of the data you are using and a description of actions that
result in unacceptable performance.
The following are examples of TM1 settings that affect performance.
VVM (}CubeProperties)
For each cube, this property determines the amount of RAM reserved on the server for the storage of stargate
views. The more memory made available for stargate views, the better performance will be. Sufficient memory
must be available for the TM1 server to load all cubes.
VMT (}CubeProperties)
If the time required to calculate a cube view surpasses the specified threshold, TM1 attempts to store a stargate
view. If there is not enough memory available to store the stargate view, TM1 purges the oldest stargate view that is
not currently in use, and continues to purge views in this manner until sufficient memory is made available.
The IBM Cognos TM1 Operation documentation includes more information about the CubeProperties and other tuning
options.
DPR-ERR-2079 Firewall Security Rejection

If you run a report after your session has expired and then try to navigate away from the first page of the report, you
encounter an error.
DPR-ERR-2079 Firewall Security Rejection. Your request was rejected by the security firewall. CAF rejection details are
available in the log. Please contact your administrator.
When the DPR-ERR-2079 error occurs after an expired session, you must log on again to resolve the problem.
Procedure
1. In the report list, right-click the node item, which appears before other items.
2. Click Log On.
3. Provide your authentication credentials as prompted and click OK.
Item cannot be expanded

Microsoft Excel has reached the maximum number of rows or columns for this worksheet. The number of rows and
columns is limited in Microsoft Excel. Expanding the current item is not possible because it would shift rows or columns
beyond this worksheet limit. Microsoft Excel cannot shift nonblank cells off the worksheet.
Manually move items so that the row or column item can expand without reaching the limit, or move your Exploration
View, list, or report to another worksheet. Or, you can move the data to a new location and try again.
Results have exceeded the Excel row or column limit

Microsoft Excel has reached the maximum number of rows or columns for this worksheet. The number of rows and
columns is limited in Microsoft Excel. Items are truncated.
Troubleshoot 177
Filter items so that the row or column items can be displayed without reaching the limit. Consider creating additional
Exploration Views, lists, or reports to spread the data over more than one worksheet. Consider using a new version of
Microsoft Excel that has larger limits for rows and columns.
Error: Exception from HRESULT:<location>

If you import a data item where the path to the data item exceeds 256 characters it results in the error: Exception from
HRESULT.
You must create names and unique data identifiers that keep to the 256-character limit inside Microsoft Excel.
Error refreshing exploration saved in earlier version of Microsoft Excel

This workbook may have been created with an older version of Microsoft Excel that has a set maximum number of rows
or columns. Rows or columns that go beyond the maximum limits are truncated.
Although you are no longer using that version, the application is working within the limits of the older version of Excel.
You might encounter this situation when you are expanding items or when you are refreshing items that have grown in
size since the workbook was created.
To correct the problem, you must save the workbook with the .xlsx extension. Opening the workbook that contains the
exploration in a more recent version of Excel does not convert it to the new format. Saving the workbook with the .xlsx
extension converts the workbook to the new format.
Security Issues
The following issues are related to security setup.
Cognos Office Unable to Create Trust Relationship

If you are using HTTPS to Report Data Service and you receive an error in IBM Cognos Office about being unable to
trust the relationship, the Certificate Authority (CA) certificate that was issued by the Web server is not trusted on the
client workstation.
To resolve this problem, you must ensure that the Certificate Authority (CA) that issued the Web server certificate is
also trusted on the client workstation. If the certificate is not from an authority that is already trusted on the client,
such as Verisign, you must install the CA certificate in the trust store on the client.
Procedure
1. Retrieve the CA certificate from the issuing authority.
The file has a .cer extension. This is not the same certificate as the one used by the Web server. It is the certificate
for the issuing authority itself.
2. Double-click the .cer file, click Install Certificate, and then click Next.
3. Click Place all certificates in the following store.
4. Click Browse, click Trusted Root Certification Authorities, and then click Next.
5. Click Finish.
Cognos Office Numbered Error Messages

The following error messages may appear in a dialog box and are recorded in the IBM Cognos Office log.
COI-ERR-2002 Block type is not valid

An internal processing error occurred. The block object was not able to be processed.
Contact IBM Cognos Resource Center. Be ready to supply all relevant logs and details related to this error.
COI-ERR-2003 Unexpected type: stacked block

An internal processing error occurred. The data object was not of the expected type and could not be processed.
COI-ERR-2005 This version of Microsoft Office is not supported
IBM Cognos Office supports only specific versions of Microsoft Office applications.
Load the report content into one of the supported applications and environments.
To review an up-to-date list of environments supported by IBM Cognos Office products, including operating systems,
patches, browsers, web servers, directory servers, database servers, and application servers, go to the IBM Support
Portal for IBM Cognos Analysis for Microsoft Excel or the IBM Support Portal for IBM Cognos for Microsoft Office.
COI-ERR-2006 This Microsoft Office product is not supported

IBM Cognos Office supports only specific Microsoft Office applications, such as Microsoft Excel, Microsoft Word, and
Microsoft PowerPoint. You cannot load IBM Cognos Office content to another Microsoft Office application, such as
Microsoft Access even when there is an add-in that enables these applications to interoperate.
Load the report content into one of the supported applications and environments.
To review an up-to-date list of environments supported by IBM Cognos Office products, including operating systems,
patches, browsers, web servers, directory servers, database servers, and application servers, go to the IBM Support
Portal for IBM Cognos Analysis for Microsoft Excel or the IBM Support Portal for IBM Cognos for Microsoft Office.
COI-ERR-2008 Unable to Retrieve from Resources. Tried '{0}'

An internal processing error occurred.
COI-ERR-2009 Unable to Perform This Operation Because Microsoft Excel is in Edit Mode
Report content cannot be refreshed while one of the cells of the workbook is being edited.
Click outside the active cell to return it to a non-edit mode and try again.
COI-ERR-2010 The name {0} is not valid. A name must not contain both a quote (") character and an apostrophe (')
character
When you create a folder, rename a folder, or publish a document, the name can contain an apostrophe or a quote, but
not both.
To resolve this problem, rename the folder or document. Exclude the apostrophe or quote character from the name.
COI-ERR-2013 Unable to load metadata

You may be unable to load metadata because you do not have security rights to all of the items in the worksheet or
because the items were removed or changed on the server.
Ensure that you have security rights to all of the items that you are trying to view. If this does not fix the problem,
ensure that the server and package information are correct and that any items that have been removed from the source
database are also removed from the worksheet.
COI-ERR-2015 There was a problem parsing the MIME encoded server response. Tried to find the boundary [{0}]
but found the boundary [{1}] instead
While using GZip compression, an option for compressing data that is retrieved from the server, an error occurred. The
codes to decompress the data are missing or unrecognized by IBM Cognos Office.
Turn compression off. Although compression is turned on by default, it can be turned off by setting the
UseGzipCompression property to false in the CommManagerSettings.xml file, which, by default, is located in the Office
Connection directory, such as C:\Documents and Settings\user name\Local Settings\Application Data\Cognos\Office
Connection or C:\Users\user name\AppData\Local\Cognos\Office Connection.
Turn compression off if you need to run tests or perform troubleshooting.
To turn gzip compression off set the following attribute:
<setting name="UseGzipCompression">False</setting>
COI-ERR-2016 Worksheet protected, IBM Cognos styles cannot be populated

If the worksheet is protected, the IBM Cognos styles cannot be applied.
You must unprotect the worksheet for the styles to be applied during a refresh of the data.
Troubleshoot 179
COI-ERR-2019 Connection failed
In Planning Analytics for Microsoft Excel, when you try to connect to a IBM Planning Analytics server, the following
error message appears:
COI-ERR-2019 Connection failed. Connection returned an error. Verify that the connection string, including the server
name and port number, is correct.
To resolve this issue, you must configure your antivirus software to allow connections from both Microsoft .NET
Runtime and Microsoft Excel.
IBM Planning Analytics for Microsoft Excel numbered error messages

The following error messages may appear in a dialog box and are recorded in the IBM Cognos Office log.
COR-ERR-2004 Axis specification is not valid

The workbook specification is not capable of being generated because of an anomaly.
To fix the problem, you may attempt to do any of the following:
• Click Undo.
• Click Clear All Data.
• Close the workbook and open it again.
The workbook should now accept data from the source tree.
COR-ERR-2007 Error retrieving from resources. Tried '{0}'

The exploration sheet experienced a bad state.
Contact IBM Cognos Resource Center.
COR-ERR-2009 Name formula is not valid

The COGNAME formula did not parse correctly. It may have been altered manually and may have a missing argument.
Check the COGNAME formula in the active cell and ensure that it is in the correct format, or optionally, insert the
member from the source tree.
COR-ERR-2010 Formula is not valid

If an argument to a COGNAME or COGVAL formula references a cell and that cell does not contain the expected string
formula you receive this error.
Check the cell and its dependents. Look for #REF or #VALUE in the cell. The contents of the cell may have accidentally
been deleted.
COR-ERR-2011 Invalid range: Please enter a valid range for crosstab or list
The range is not valid or is outside of the range of the data type.
To avoid this limitation, limit your data selections.
COR-ERR-2013 Exploration cannot be converted to formula based because at least one context item contains a
selection
With more than one item in the Context drop zone there is no way for the multiple items to be rendered into the cells of
the worksheet.
Remove one dimension from the Context drop zone. You must have one item per dimension to convert to a formula-
based analysis.
COR-ERR-2014 Due to Excel worksheet limitations the results may be truncated

If the data that you receive back exceeds the row or column limits of Microsoft Excel, the result is truncated. You
receive this message to make you aware of the truncation.
To avoid this limitation, limit your data selections.
COR-ERR-2015 The current exploration cannot be rendered at this location on the worksheet
The exploration cannot write data outside the limits of the current worksheet. Either the exploration is too large for
Microsoft Excel or you have designated a starting location too close to the limit.
Try to move your start location. If that fails to fix the problem, try creating an Exploration View with fewer rows or
columns.
COR-ERR-2016 Unable to retrieve package <Name>

After you selected a package using the Open Package dialog box, an error occurred when trying to download the
package from the server.
This is an internal error.
Contact IBM Cognos Resource Center.
ValueNotInPickList (243)
The value you are trying to commit is not an available option in the picklist.
When entering a value into a report cell, ensure that the value is an available option in the picklist.
Microsoft Excel limits

There are specifications and limits in Microsoft Excel 2013-2016 that may affect the performance of Planning Analytics
for Microsoft Excel.
The following tables group the specifications and limits into categories:
• Worksheet and workbook
• Calculation
Table 39: Specifications and limits that apply to worksheets and workbooks
Specification Maximum limit Notes
Column width 255 characters If the data that you enter or receive
exceeds the column limits of Microsoft
Excel, the result is truncated.
Row height 409 points If the data that you enter or receive
exceeds the row limits of Microsoft
Total number of characters that a cell 32,767 characters If the data that you enter or receive
can contain exceeds the cell character limits of
Microsoft Excel, the result is truncated.
Maximum limits of memory storage and 32-bit environment is subject to 2 Due to the limitations with add-ins,
file size for Data Model workbooks gigabytes (GB) of virtual address space, users can only copy and paste once on
shared by Excel, the workbook, and top of a DBRW formula.
add-ins that run in the same process. A
Adding tables to the Data Model
data model’s share of the address space
increases the file size. If you don’t plan
might run up to 500 – 700 megabytes
to create complex Data Model
(MB), but could be less
relationships using many data sources
if other data models and add-ins are and data types in your workbook,
loaded. uncheck the Add this data to the Data
Model box when you import or create
64-bit environment imposes no hard
tables, pivot tables, or data
limits on file size. Workbook size is
connections.
limited only by available memory and
system resources.
Troubleshoot 181
Table 40: Specifications and limits that apply to calculations
Specification Maximum limit Notes
Length of formula contents 8,192 characters If the formula that you enter exceeds
the formula content limit of Microsoft
Internal length of formula 16,384 bytes If the formula that you enter exceeds
the internal length of formula limit of
Microsoft Excel, the result is truncated.
Number of arguments that worksheet 30 Due to a limitation with Microsoft Excel,
functions can contain worksheet functions can contain no
more than 30 arguments. When you
construct a cube reference,
one argument must be the cube name,
which leaves 29 arguments for
specifying the cube dimensions.
Appendix A. Sample reports and packages
The IBM Cognos for Microsoft Office products include sample reports and packages that are based on the sample
company, The Sample Outdoors Company. After the samples are set up, you can find the samples in Public Folders in
IBM Cognos Connection, and in the source tree on the IBM Cognos pane.
The Sample Outdoors Company

The Sample Outdoors Company samples illustrate product features and technical and business best practices.
You can also use them for experimenting with and sharing report design techniques and for troubleshooting. As you use
the samples, you can connect to features in the product.
The Sample Outdoors Company, or GO Sales, or any variation of the Sample Outdoors name, is the name of a fictitious
business operation whose sample data is used to develop sample applications for IBM and IBM customers. Its
fictitious records include sample data for sales transactions, product distribution, finance, and human resources. Any
resemblance to actual names, addresses, contact numbers, or transaction values, is coincidental. Unauthorized
duplication is prohibited.
Samples outline
The samples consist of the following:
• Two databases that contain all corporate data, and the related sample models for query and analysis
• Sample cubes and the related models
• A metrics data source including associated metrics and a strategy map for the consolidated company, and a model
for Metric extracts.
• Reports, queries, query templates, and workspaces
To run interactive reports, scripts are required. To see all the reports included in the samples packages, copy the files
from the samples content installation into deployment folder and then import the deployments into the IBM Cognos
Business Intelligence product.
Security
Samples are available to all users.
To implement security, see the IBM Cognos Business Intelligence Administration and Security Guide.
The Sample Outdoors Group of Companies

To make designing examples faster, especially financial examples, some general information about The Sample
Outdoors Company is useful.
To look for samples that use particular product features, see the individual sample descriptions in this section.
Revenue for The Sample Outdoors Company comes from corporate stores and from franchise operations. The revenues
are consolidated from the wholly-owned subsidiaries. There are six distinct organizations, each with its own
departments and sales branches. Five of these are regionally-based companies.
The sixth company, GO Accessories:
• Has its own collection of products, differentiated from the other GO companies by brand, name, price, color and size.
• Sells from a single branch to all regions and retailers.
• Functions both as an operating company based in Geneva, and as a part owner of the three GO subsidiaries in Europe.
The following diagram illustrates the consolidated corporate structure of the Sample Outdoors Company. The diagram
also includes the percentage changes in ownership for GO Central Europe, and the reporting currency and GL (general

ledger) prefix for each subsidiary. In year 1, GO Asia Pacific owns 60% of GO Central Europe, and in year 3, its
ownership decreases to 50%. In year 1, GO Accessories owns 40% of GO Central Europe, and in year 3 its ownership
increases to 50%.
Figure 11: Consolidated corporate structure of the Sample Outdoors Company
Each corporation in the Sample Outdoors Company has the same departmental structure and the same general ledger
(GL) structure, as shown in the following table. Divisions may not report in the same currencies. For example, the
Americas subsidiary reports in US dollars, but the Corporate division local currency reports in Canadian dollars, and the
Operations division local currency is pesos.
Table 41: Departmental structure
Division (GL) Department (GL)
Corporate (1700) Sales (1720)

Marketing (1750)
IS&T (1760)
Human Resources (1730)
Finance (1740)
Procurement (1710)
Operations (1800) Production and Distribution (1820)

Customer Service (1820)
Each corporation has a complete chart of accounts. Most of the accounts, such as those under non-personnel
expenses, are at the department level, and contain only summary amounts. For example, although each marketing
department has expenses, the cost is unspecified at the transaction level where marketing promotions occur.
Employees
The Sample Outdoors data contains a full list of employees in all divisions, departments, and locations.
Data is available for reports about bonuses (Global Bonus report) and sales commissions (Sales Commissions for
Central Europe report), training (Employee Training by Year report), and performance reviews and employee
satisfaction surveys (Employee Satisfaction 2012). If you use Metric Studio, sample metrics for human resources are
also available.
In the GO Data Warehouse (analysis) package, groups of measures and the related dimensions are organized into
folders. The employees are organized in hierarchies for region and manager, to make different kinds of aggregation easy
to report on. Aggregation has been defined for the Employee Position Summary measures, so that Position count and
Planned position count aggregate correctly at each level of time: monthly, quarterly, or yearly. For example, see the
Planned Headcount report.
The employees are also listed in a sample LDIF file which could be used for any LDAP IBM product authentication
including Tivoli®. This authentication directory is necessary for IBM Cognos Planning samples. No other samples
depend on security profiles.
Sales and marketing

Data about sales and marketing is available for all of the companies in the Sample Outdoors group.
GO Accessories has richer details to support analysis examples. For example, see the Revenue vs % Profit Margin by
Product Brand analysis, based on the Sales and Marketing cube. Marketing and sales campaigns are tied to the Sample
Outdoors regional companies.
Overall, the GO companies have experienced solid growth across most product lines (Sales Growth Year Over Year), in
all regions (Revenue by GO Subsidiary 2011), because of factors like an increase in repeat business and new or
improved products, such as the high margin sunglasses product line. In the product lines sold by the five regional
companies (all but GO Accessories) promotions have had mixed success (Promotion Success by Campaign, Bundle and
Quarter). If you use Metric Studio, this can also be seen in the sample metrics.
Customer surveys
The data also contains information from customer surveys. For example, the product line that includes bug spray, sun
screen, and so on has not been successful (Product Satisfaction - Outdoor Protection 2011) and a source of retailer
dissatisfaction may be the level of customer service rather than the returns (Customer Returns and Satisfaction). If you
use Metric Studio, this information can also be monitored in metrics.
Sales outlets
Revenue from the corporate outlets is available at the transaction level. Revenue from the franchise outlets is available
at the consolidated level only (Sales and Marketing cube). Metrics about retailers show that the number of new retail
outlets has dropped over the time period covered by this data.
GO Accessories sells worldwide, and sells only accessories. Transaction data for GO Accessories is the primary source
for analysis of product by brand, color and size. The other five subsidiaries in the group of companies are regional and
sell all product lines for retailers in their region. For example, the report Top 10 Retailers in 2011 uses sparklines and
list data to review revenues at the retailer level.
Sample Outdoors database, models, and packages

The Sample Outdoors Framework Manager models illustrate modeling techniques and support the samples.
The models are based on the GO data warehouse and the GO sales transactional database and are the basis for the
sample reports and queries. Each model contains two packages for publishing analysis (dimensional) and query views
of the data.
Sample reports and packages 185

You must have access to Framework Manager, the modeling tool in IBM Cognos Business Intelligence, to look at the
sample models. You may also need to set up the sample databases and connections.
GO Data Warehouse
The GO Data Warehouse model, great_outdoors_data_warehouse.cpf, is based on the database GOSALESDW. It

contains data about human resources, sales and marketing, and finance, grouped into business areas. In the Database
view, the three business areas are grouped into separate namespaces. The Database view contains a fourth namespace
(GO Data) for the common information.
The Database view is very similar to the structure of the underlying database. All tables (database query subjects) are
unchanged. This enables IBM Cognos BI to retrieve metadata directly from the package in most cases, instead of using
a metadata call to the database. The following changes and additions have been made in the Database view:
• Joins have been added as necessary.
• To allow for aggregation at different levels of granularity, some model query subjects have been created. For
example, see the relationships between Time and Sales or Sales fact.
• To allow single joins to be made between the lookup tables and each level in a dimension, lookup tables have been
copied. For example, see the Products look up tables.
The Business view contains only model query subjects, with no joins. The following changes and additions have been
made in the Business view:
• Calculations were added to the model query subjects. For example, the time dimension contains language
calculations.
• Where the database has multiple hierarchies, new dimensions have been created to organize each hierarchy. For
example, the employee hierarchies are organized into several categories, such as manager and region.
The GO Sales transactional database
The GO Sales model, great_outdoors_sales.cpf, is based on the GOSALES database, which is structured as a
transactional database. It contains principally sales data.
The Database view is very similar to the underlying database structure. The following changes and additions have been
made in the Database view:
• To make it possible to join the fact tables to the time dimension, model query subjects and multipart joins have been
used.
• Other joins have been added as necessary.
The Business view contains only model query subjects, with no joins. The following changes and additions have been
made in the Business view:
• Calculations were added to the model query subjects.
• Model query subjects that were created in the Database view to enable joins on the time dimension have been linked
as reference shortcuts.
• Where the database has multiple hierarchies, new dimensions have been created to organize each hierarchy.
• Sales Staff is a subset of the slowly changing Employee dimension. There is no unique Employee key in GO Sales, so a
filter retrieves the current record only. This model does not use historical data.
The samples PowerCubes
The following cubes are delivered with the Sample Outdoors samples in English, French, German, Japanese and
Chinese:
• sales_and_marketing.mdc
• employee_expenses.mdc
• go_accessories.mdc
• go_americas.mdc
• go_asia_pacific.mdc
• great_outdoors_sales_en.mdc
• great_outdoors_7.mdc
The samples packages
The Sample Outdoors samples include six packages. A brief description of each available package is provided.
Go Data Warehouse (analysis) is a dimensionally modeled view of the GOSALESDW database. This package can be used
in all studios, including IBM Cognos Analysis Studio. Using this package you can drill up and down.
Go Sales (analysis) is a dimensionally modeled view of the GOSALES database. This package can be used in all studios,
including Analysis Studio. Using this package you can drill up and down.
Go Data Warehouse (query) is a non-dimensional view of the GOSALESDW database. This package can be used in all
studios except Analysis Studio, and is useful for reporting when there is no need for drilling up and down.
Go Sales (query) is a non-dimension view of the GOSALES database. This package can be used in all studios except
Analysis Studio, and is useful for reporting when there is no need for drilling up and down.
Sales and Marketing (cube) is an OLAP package, based on the sales_and_marketing.mdc cube.
Great Outdoor Sales (cube) is an OLAP package, based on the great_outdoors_sales_en.mdc cube.
Note: The OLAP packages, Great Outdoor Sales (cube) and Sales and Marketing (cube), are not multilingual. The
IBM_Cognos_PowerCube.zip archive contains five versions of each package; one in English, French, German,
Japanese and Chinese.
Samples in the GO Data Warehouse (analysis) package

The following are some of the reports found in the GO Data Warehouse (analysis) package and GO Office Report
Samples.
Employee Satisfaction Workspace

This workspace shows different measures of employee satisfaction, like training, bonuses, and employee survey
scores. The bonus list is filtered by country.
Return Quantity by Order Method

This report shows quantity sold, number of returns, and percentage of returns (with those greater than 5% highlighted)
by return reason for each product in the Outdoor Protection product line. This report uses the following features:
• filters
• lists
• conditional highlighting
• grouping
Return Quantity by Product Line Chart

This pie chart report shows return quantities of product lines for all subsidiaries.
Revenue Data Workspace

The workspace shows revenue by region, by country and product type (filtered with multiple values check boxes), and
by order method.
Samples in the GO Data Warehouse (query) package

The following reports are some of the reports found in the GO Data Warehouse (query) package and GO Office Report
Samples.

Baselines
This chart report shows the numeric baselines, mean and percentage, based on prompt values that are used to filter on
years.
Bursted Sales Performance Report

This list report shows how to burst a sales performance report to a manager of Northern Europe sales staff. To
successfully burst this report, IBM Cognos 10 must be configured to use an email server. This report uses the following
features:
• lists
• bursting
• conditional highlighting
• filters
• calculations
• summarizing
• blocks
• custom headers and footers
• sorting
• grouping
Samples in the Sales and Marketing (Cube) package

The following reports are some of the reports found in the Sales and Marketing (Cube) package and GO Office Report
Samples.
Revenue by Product Brand

This report shows the revenue and gross profit by product filtered by the product brand. There is always product
turnover, so the report conditionally highlights products that are discontinued. This report uses the following features:
• lists
• filters
• prompts
• combination charts
• bar charts
• HTML items
• grouping
• sorting
• axis titles
Samples in the GO Sales (analysis) package

The following reports are some of the reports found in the GO Sales (analysis) package and GO Office Report Samples.
Sales Summary
This report summarizes revenue and gross profit and shows the top sales representatives by revenue and quantity sold.
This report uses the following features:
• lists
• filters
• combination charts
• axis titles
• conditions
Samples in the GO Sales (query) package
The following reports are some of the reports found in the GO Sales (query) package and GO Office Report Samples.
Horizontal Pagination
This report shows a very wide Exploration View rendered across several horizontal pages. The first Exploration View
shows the fit-to-page behavior, while the second Exploration View shows the horizontal pagination.
• multiple pages
• horizontal pagination
• Exploration Views
No Data
Each page of this report presents a different option for dealing with a No Data condition. It also generates invoices of
sales for the Order Invoices - Donald Chow, Sales Person report in the GO Sales (query) package.
• Exploration Views
• no data
• lists

Appendix B. Accessibility features
IBM Planning Analytics for Microsoft Excel has accessibility features that help users who have a physical disability, such
as restricted mobility or limited vision, to use information technology products successfully.
The following list includes the major accessibility features :
• You can use accelerators and command keys for navigation.
In Microsoft Windows, press the Alt key, then the accelerator to trigger an action; for example, Alt+F shows the File
menu. If they are enabled, you can use extended accelerators as well.
• IBM Planning Analytics for Microsoft Excel uses Microsoft Active Accessibility (MSAA). This means that people with
limited vision can use screen-reader software, along with a digital speech synthesizer, to listen to what is displayed
on the screen.
• IBM Planning Analytics for Microsoft Excel supports your system's display settings, such as color scheme, font size,
and high-contrast display.
• IBM Planning Analytics for Microsoft Excel provides text through standard system function calls or through an API
(application programming interface) that supports interaction with assistive technology, such as screen-reader
software. When an image represents a program element, the information conveyed by the image is also available in
text.
https://helpline.hursley.ibm.com has other features that you can customize to fit your individual needs:
• “Increase font size for future sessions” on page 195
• “View explorations in Windows high contrast mode” on page 195
Keyboard navigation
You can use keyboard shortcuts to navigate and perform tasks. If an action you use often does not have a shortcut key,
you can record a macro in Microsoft Excel to create one.
This product uses standard Microsoft Windows navigation keys in addition to application-specific keys.
Note: The keyboard shortcuts are based on U.S. standard keyboards. Some of the content in this topic may not be
applicable to some languages.
Access and use menus

Keyboard shortcuts allow you to access menus and the IBM Planning Analytics ribbon without using a mouse or other
pointing device.
Note: Shortcut keys may vary depending on the individual setup and operating systems used.
Table 42: IBM Planning Analytics ribbon
Action Shortcut keys
Start IBM Planning Analytics for Microsoft Excel or IBM ALT+Y, to place focus on the IBM Planning Analytics tab in
Cognos for Microsoft Office. the ribbon.
When an item on the IBM Planning Analytics tab is selected, LEFT ARROW, RIGHT ARROW, UP ARROW, or DOWN ARROW
select the next or previous button or menu on the tab.
Select the first or last command on the menu or submenu. HOME or END
Open the selected menu, or perform the action for the ENTER
selected button or command.

Table 42: IBM Planning Analytics ribbon (continued)
Open the context menu for the selected item or area of focus. SHIFT+F10
Close an open context menu. ESC
Access and use the task pane

Keyboard shortcuts allow you to access the task pane without using a mouse or other pointing device.
Table 43: Task pane
Selecting a database to log onto. Office 2013 and 2016 users:

Note: A menu or the IBM Planning Analytics tab must be • Move the focus to the task pane by holding Shift and
active when performing this action. pressing F6 3 times.
Note: The focus will be moved to the task pane, however,
there is no visual representation to indicate this.
• Select the server by pressing tab 2 times. The Open icon
will be highlighted. Press SPACE and then press the DOWN
ARROW to open and navigate the sub menu.
• Select the database by pressing the RIGHT ARROW and
then pressing ENTER.
When the task pane is active, select a component, such as Office 2013 and 2016 users:
IBM Planning Analytics for Microsoft Excel or IBM Cognos for
LEFT ARROW or RIGHT ARROW
Microsoft Office
Office 2010 users:
CTRL+TAB
LEFT ARROW or RIGHT ARROW
When the IBM Cognos Office pane is active, select the next or Office 2013 users:
previous option in the pane.
TAB
Office 2010 users:
CTRL+TAB
Place the focus on the metadata tree. CTRL+M, T
Place the focus on the overview area of an Exploration View. CTRL+M, U
Use windows
Keyboard shortcuts allow you to access dialog boxes without using a mouse or other pointing device.
Table 44: Dialog boxes or windows
Move to the next option or option group. TAB
Table 44: Dialog boxes or windows (continued)
Move to the previous option or option group. SHIFT+TAB
Move between options in an open drop-down list, or between Arrow keys

options in a group of options.
Perform the action for the selected button, or select or clear SPACEBAR
the selected check box.
Open the context menu, if it is closed, and move to that SHIFT+F10, then press the first letter of an option in a drop-
option in the context menu. down list
Open the selected drop-down list. DOWN ARROW

First letter of an option in a drop-down list
Close the selected drop-down list. Office 2013 users:

ESC
Office 2010 users:
First letter of an option in a drop-down list
Expand or collapse a folder. Office 2013 users:

RIGHT ARROW, LEFT ARROW
Office 2010 users:
CTRL+ENTER
Cancel the command and close the window. ESC
Open the Select Package dialog box. CTRL+M, O
When the Open dialog box is active, open the selected report ENTER
locally.
When the Select Package dialog box is open, select a Office 2013 users:
package.
TAB, to place focus on the System box
DOWN ARROW, to select a Cognos system
ENTER to view the packages
Office 2010 users:
TAB, to place focus on the System box
ENTER to view the packages
When the Publish dialog box is active and the appropriate After selecting the file name, tab to the Publish button and
folder is expanded, publish the selected Microsoft Office press ENTER.
document.
In IBM Cognos for Microsoft Office, move to a tab page, such CTRL+TAB
as the Browse Content or the Manage Data page, on the
IBM Cognos pane.
Accessibility features 193

Use tree view
Keyboard shortcuts allow you to access tree view without using a mouse or other pointing device.
Table 45: Tree view
Move to the first selectable node. DOWN ARROW

If the node has children and the child node is expanded,
move to the first child node.
Move to the next selectable node. UP ARROW or DOWN ARROW
Expand the selected node, or move to the first selectable RIGHT ARROW
child node
Collapse the selected node, move to the parent node, or LEFT ARROW
move to the first selectable node.
Move to the first node in a tree control. HOME
Move to the last node in a tree control. END
Use report options

Keyboard shortcuts allow you to perform report actions.
Table 46: Report options
Undo the most recent action in the exploration. CTRL+M, Z
Redo the most recent action in the exploration. CTRL+M, Y
Expand or collapse a consolidated element in a Dynamic CTRL+M, G

Report.
Edit the annotation for the selected cell. CTRL+M, A
Commit the changed value for the selected cell. CTRL+M, C
Hold the value in the selected cell, or release a hold on a cell. CTRL+M, H
Refresh the current Quick Report or Exploration View. CTRL+M, R
Clear the data from the current Quick Report. CTRL+M, L
Refresh all Quick Reports on the worksheet CTRL+M, W
Show the properties for the current Quick Report. CTRL+M, P
Commit changed values in the current Quick Reports. CTRL+M, C
Interface information
The following sections describe various ways that you can customize your settings to make IBM Planning Analytics for
Microsoft Excel more accessible.
Increase font size for future sessions

It is best to change the size of your IBM Planning Analytics for Microsoft Excel fonts by changing your display fonts in
Windows. Changing your Windows display fonts affects all programs on your computer. For more information, refer to
Windows Help.
View explorations in Windows high contrast mode

Microsoft Windows users with low vision can make IBM Planning Analytics for Microsoft Excel easier to view by
enabling High Contrast Mode. For more information, see the documentation for your operating system.
Vendor software
IBM Planning Analytics for Microsoft Excel includes certain vendor software that is not covered under the IBM license
agreement. IBM makes no representation about the accessibility features of these products. Contact the vendor for the
accessibility information about its products.
IBM and accessibility

See the IBM Human Ability and Accessibility Center for more information about the commitment that IBM has to
accessibility.
http://www.ibm.com/able
Accessibility features 195

Appendix C. Rebrand Cognos Office Components
This section is intended for clients and partners who need to rebrand, customize, or localize labels, messages, or other
strings in IBM Cognos Office products, such as IBM Planning Analytics for Microsoft Excel, IBM Cognos Office, and IBM
Cognos for Microsoft Office.
Resource Files
All the customizable strings for IBM Cognos Office products are in XML-based resource (.resx) files.
The .resx resource file format consists of XML entries that specify objects and strings inside XML tags. One advantage of
a .resx file is that when opened with a text editor (such as Notepad) it can be written to, parsed, and manipulated.
When viewing a .resx file, you can see the binary form of an embedded object, such as a picture when this binary
information is a part of the resource manifest. Apart from this binary information, a .resx file is readable and
maintainable.
A .resx file contains a standard set of header information that describes the format of the resource entries, and
specifies the versioning information for the XML code that parses the data.
These files contain all the strings, labels, captions, and titles for all text in the three IBM Cognos Office components. For
each language, there are three files, one for each component. The following table identifies each of the files.
Table 47: IBM Cognos Office resource files
Language IBM Planning Analytics for IBM Cognos for Microsoft IBM Cognos Office files
Microsoft Excel files Office files
(internal name coi)
(internal name cor) (internal name coc)
Language Neutral cormsgs.resx cocmsgs.resx coimsgs.resx
Chinese (simplified) cormsgs.zh-cn.resx cocmsgs.zh-cn.resx coimsgs.zh-cn.resx
Chinese (traditional) cormsgs.zh-tw.resx cocmsgs.zh-tw.resx coimsgs.zh-tw.resx
Croatian cormsgs.hr.resx cocmsgs.hr.resx coimsgs.hr.resx
Czech cormsgs.cs.resx cocmsgs.cs.resx coimsgs.cs.resx
Danish cormsgs.da.resx cocmsgs.da.resx coimsgs.da.resx
Dutch cormsgs.nl.resx cocmsgs.nl.resx coimsgs.nl.resx
English cormsgs.en.resx cocmsgs.en.resx coimsgs.en.resx
Finnish cormsgs.fi.resx cocmsgs.fi.resx coimsgs.fi.resx
French cormsgs.fr.resx cocmsgs.fr.resx coimsgs.fr.resx
German cormsgs.de.resx cocmsgs.de.resx coimsgs.de.resx
Hungarian cormsgs.hu.resx cocmsgs.hu.resx coimsgs.hu.resx
Italian cormsgs.it.resx cocmsgs.it.resx coimsgs.it.resx

Table 47: IBM Cognos Office resource files (continued)
Language IBM Planning Analytics for IBM Cognos for Microsoft IBM Cognos Office files
Microsoft Excel files Office files
(internal name coi)
(internal name cor) (internal name coc)
Japanese cormsgs.ja.resx cocmsgs.ja.resx coimsgs.ja.resx
Kazakh cormsgs.kk.resx cocmsgs.kk.resx coimsgs.kk.resx
Korean cormsgs.ko.resx cocmsgs.ko.resx coimsgs.ko.resx
Norwegian cormsgs.no.resx cocmsgs.no.resx coimsgs.no.resx
Polish cormsgs.pl.resx cocmsgs.pl.resx coimsgs.pl.resx
Portuguese cormsgs.pt.resx cocmsgs.pt.resx coimsgs.pt.resx
Romanian cormsgs.ro.resx cocmsgs.ro.resx coimsgs.ro.resx
Russian cormsgs.ru.resx cocmsgs.ru.resx coimsgs.ru.resx
Slovenian cormsgs.sl.resx cocmsgs.sl.resx coimsgs.sl.resx
Spanish cormsgs.es.resx cocmsgs.es.resx coimsgs.es.resx
Swedish cormsgs.sv.resx cocmsgs.sv.resx coimsgs.sv.resx
Thai cormsgs.th.resx cocmsgs.th.resx coimsgs.th.resx
Turkish cormsgs.tr.resx cocmsgs.tr.resx coimsgs.tr.resx
Run Cognos Office components in English in a localized Microsoft Windows

environment
You can display English in Cognos Office components in a Microsoft Windows environment that is configured to use
another language.
About this task

For example, if Microsoft Windows is set to use French, Cognos Office components also use French by default. But you
can configure Cognos Office components to use English instead of French.
Procedure
1. Close all Microsoft Office windows.
2. In Windows Explorer, navigate to the Cognos Office installation location.
Tip: On Windows 7, the default installation location is C:\Program Files (x86)\IBM\cognos\Cognos for
Microsoft Office.
3. Find the folder that corresponds to the locale you are using in Windows, for example, fr if you are using French in
Microsoft Windows.
4. Move the folder to a location outside of the Cognos Office installation location.
Example
For example, if your Region and Language settings in Windows are set to French (France), but you want to see English in
IBM Planning Analytics for Microsoft Excel, move the fr folder outside of the Cognos for Microsoft Office
folder. When you open IBM Planning Analytics for Microsoft Excel, or any other Cognos Office component, the user
interface is in English.
Rebrand or Localize Cognos Office Components

If you are setting the IBM Cognos component for a multilanguage environment, you must compile both the language-
neutral file and the language file for your locale. The program detects the user locale settings in Windows and uses the
appropriate language file.
For example, suppose you installed IBM Planning Analytics for Microsoft Excel and your locale is set to French (France).
You must make changes to the language-neutral files: cormsgs.resx and coimsgs.resx, and to the French files:
cormsgs.fr.resx and coimsgs.fr.resx.
To customize or localize the component names and text messages, follow these steps:
• Edit the language-neutral resource files, and if necessary, the language resource files for your locale.
• Download and then run the Resource File Generator (Resgen.exe) required for compiling the updated resource files.
• Test your work.
Editing the resource (.resx) files

For each component, there exists a set of files that support the various languages. The country or region code
distinguishes the filenames.
With the exception of the language-neutral set of files (cormsgs.resx, cocmsgs.resx, and coimsgs.resx) that serve as the
default files, each file follows the following naming convention:
componentcodemsgs.languagecode.resx
You can change strings, not icon or graphic resources.
When changing text strings, consider the string length. The width of fields were created using the existing strings.
Significantly increasing string length may result in some strings getting truncated in some of the dialog boxes.
The resource file contains metadata and comments that can help you determine when and where strings are used in
the software.
Important: To edit XML resource files, use an XML editor. It is important to preserve the Unicode encoding and format,
including white space. Simple text editors will likely corrupt the files. A validating XML editor ensures that the contents
of the files are well formed and valid. Modify only string information. Do not change other information in the files.
Procedure
1. Install the IBM Cognos Office components locally to a workstation.
This gives you access to the resource files.
2. Locate the resource files.
If you install locally and accept all the defaults, they are found in the following location:
[installation directory]\Program Files\IBM\cognos\Cognos for Microsoft Office
\resources
3. In an XML Editor, open the componentcodemsgs.languagecode.resx file.
Use an editor such as Visual Studio or XMLSpy to change the branding details or to translate strings into another
language.
If you are creating new language files, follow the naming convention by inserting the 2 or 5-character language code
into the middle of the file name. For example, if you add a Romanian language file for IBM Cognos for Microsoft
Office, you would save it as cocmsgs.ro.resx.
Rebrand Cognos Office Components 199

4. Save the file.
5. Repeat steps 3 and 4 for each component file associated with the language that you want to translate.
Results
The updated resource files are now ready to be compiled.
Compile the updated resource files

Before you can deploy updated files, you must download the Resource File Generator (Resgen.exe). The Resource File
Generator converts .txt files and .resx (XML-based resource format) files to common language runtime
binary .resources files that you can embed in a runtime binary executable or compile into satellite assemblies.
The Resource File Generator is a Microsoft .NET Framework Software Development Kit (SDK) program that generates
compiled resource files. The resgen executable is shipped with the Microsoft .NET SDK and comes with Microsoft Visual
Studio development system. You must choose a version of the Resource File Generator that is compatible with the
version of .NET Framework that is used by IBM Cognos Office components.
Resgen.exe performs the following conversions:
• Converts .txt files to .resources or .resx files.
• Converts .resources files to text or .resx files.
• Converts .resx files to text or .resources files.
Procedure
1. Download the resgen.exe from the Microsoft .NET developer Web site.
2. After downloading the Resource File Generator, open a command prompt window.
3. Find the location where Resgen was downloaded.
For example, cd C:\Program Files\Microsoft Visual Studio 8\v2.0\Bin
4. To compile the resource files, from the command prompt, type
resgen /compile "[resx file location]\[file name.resx]"
For example, resgen /compile "c:\ProgramFiles\Cognos\Cafe\resources\cormsgs.resx"
Resource files are automatically renamed to include the .resource extension in their file name.
5. Copy the resulting files to the Resources directory.
Test your work

To test your work, run IBM Cognos Office using a variety of locales and start each component (IBM Cognos Office, IBM
Cognos for Microsoft Office, and IBM Planning Analytics for Microsoft Excel) to ensure that your changes are reflected
in each area.
Check the text changes in all the interfaces exposed to your users. Pay particular attention to generic dialog boxes,
which are easy to miss.
Appendix D. Settings in the
CognosOfficeReportingSettings.xml file
You can configure IBM Planning Analytics for Microsoft Excel by using the CognosOfficeReportingSettings.xml
file. The file is located in C:\Users\[User]\AppData\Local\Cognos\Office Connection.
The following tables group the settings into categories:
• Settings that apply to all supported data sources
• Settings that apply only when you are using a TM1 data source
Table 48: Settings that apply to all supported data sources

Name Description Allowed values Default value
CommitWithoutConfirmation Commits valid data without True, False False
prompting you to confirm the
commit.
You can also turn this feature
on or off by using the Hide
commit confirmation option
in the Options dialog box. Or
you can use the Hide commit
confirmation option in the
Commit Changes dialog box.
ContextMemberLimit Sets the number of members Integer 15

to display in the drop-down
list for dimensions in the
context area of Exploration
Views. Click More to see
more members.
ConvertDropDown Sets the default conversion Quick Reports: MapOnNewSheet
option displayed on the MapOnNewSheet,
explorations toolbar (used for MapOnThisSheet,
converting to another report MapAtSpecifiedLocation
type).
Formulas:
FormulasOnNewSheet,
FormulasOnThisSheet,
FormulasAtSpecifiedLocation
None
CustomStartingRange Prompts you for a starting True, False False

cell when you create
explorations.
on or off by using the Assign
Exploration View or list
starting cell option in the
Options dialog box.

Table 48: Settings that apply to all supported data sources (continued)
DataRowLimit Specifies the number of rows Integer 500
to retrieve from the server
and display in explorations, 0
= no limit.
You can also set this by using
the Data display row limit
option in the Options dialog
box.
Note: This is a global setting
for all explorations in a
workbook. You can override
this setting in the Properties
dialog box for Exploration
Views and lists.
DefaultRefreshMode Sets the default refresh None None

button displayed on the
RunAllData: Refresh data and
explorations toolbar.
formatting
For example, if you set
RunAllDataWithout
DefaultRefreshMode=
Formatting: Refresh data only
PreviewOnly, the Preview
with No Data button is PreviewOnly: Preview without
displayed on the explorations data
toolbar.
ExplorationOverride Overrides the double-click True, False True

DoubleClick action in explorations.
GroupingOption Sets the way in which cells None Full
are grouped when you nest
Sparse: Labels the top cell
dimensions.
only
You can also set the grouping
Normalized: Repeats labels
option by using the Grouping
option in the Options dialog Full: Merges cells
box.
Note: This is a global setting
for all explorations in a
workbook. You can override
this setting in the Properties
dialog box for Exploration
Views and lists.
InsertDetails Sets the default insert mode None InsertSingle Member
displayed on the explorations
InsertSingleMember
toolbar.
InsertMemberWithChildren
For example, if you set
InsertDetails= InsertMemberWithChildren
InsertSingleMember, the Dynamic
Insert Single Member button
InsertMemberWith
is displayed on the
Descendants
InsertMemberWithInputs
InsertMemberWithAncestors
MemberLimit Sets the maximum number of Integer 1000

child members to show in the
source tree.
You can also set this option
by using the Member display
count limit option in the
Options dialog box.
MruPackage Contains information about

the most recently used data
source.
MruServer Contains information about
the most recently used
Cognos system.
RefreshConfirmation Displays a confirmation True, False True
dialog box when you refresh a
workbook or worksheet.
on or off by using the Hide
refresh confirmation for
each worksheet and
workbook option in the
Options dialog box.
RefreshDropDown Stores the refresh mode most None RunAllData

recently used on the
RunAllData: Refresh and
apply server formatting
RunAllDataWithout
Formatting: Refresh and
apply Excel formatting
PreviewOnly: Preview without
data
Settings in the CognosOfficeReportingSettings.xml file 203

ShowServerInExploration Displays an information area True, False True
above explorations. The
information area displays
details such as the server,
row dimensions, column
dimension, and so on.
on or off by using the Show
system and package
information in the
Exploration View and list
sheet option in the Options
dialog box.
UseMruPackage Loads the most recently used True, False False

data source at startup.
on or off by using the Load
most recently used system
and package option in the
Options dialog box.
Table 49: Settings that apply only to reports that use IBM TM1 data sources
ActionButtonBackupDir Sets the default directory for Path C:\Users\<User>\Desktop
backing up workbooks when
upgrading action buttons.
ActionButtonLogDir Sets the default directory for Path C:\Users\<User>\Desktop
saving the logs when
upgrading action buttons.
AllowAdvanceQueryUI Displays the Show MDX True, False False
button on the Exploration
View toolbar.
AllowContextSum Enables you to select a sum True, False True
of items for context
dimensions in Exploration
Views.
In an Exploration View, click
the drop-down for a
dimension in the context area
and click Sum.
AllowFormulaWriteBack Enables the DBR, DBRA, True, False True

DBSA, and DBRW functions to
write values back to the TM1
server.
Table 49: Settings that apply only to reports that use IBM TM1 data sources (continued)
AutoSpread Converts values entered in True, False True
ConsolidatedInput consolidated cells into
proportional spread
operations.
BulkUploadAutoCommitValid Commits values in valid True, False True
intersections of a Quick
Report automatically, without
validating the values first.
on or off by using the
Automatically commit valid
intersections option in the
Error Report dialog box.
DefaultExpandDirection Sets the direction to expand EXPAND_ABOVE: Expands EXPAND_ABOVE

when you double-click in an child members above their
Exploration View or list. parent.
You can also change this EXPAND_BELOW: Expands
setting by using the Expand child members below their
Direction option in the parent.
Properties dialog box for
Exploration Views and lists.
Expansions Defines macros for data A JSON expression {{"TM1": {"k":"1000",

entry: k, m, q, or user- "m":"1000000", "q":".001"}}}}
defined. These macros are
applied to a value before it is
committed to the TM1 server.
FlexviewDefaultIndentOn Sets Quick Reports to indent True, False True
by default.
FlexViewDoubleClickAction Defines the double-click None: This allows the normal None
action for Quick Reports. You Excel behavior to occur,
can also set this option by which is to edit the cell.
using the Double-click
ExpandAbove: Double
action option in the Options
clicking a consolidated
dialog box.
member expands the
children above their parent.
ExpandBelow: Double
clicking a consolidated
member expands the
children below their parent.
Replace: Double clicking any
member displays the set
editor, which you can use to
replace the member.

IncludeControlObjects Displays the control cubes of True, False False
a TM1 data source in the
Select Package dialog box.
You can select a cube and
use it to create reports.
IncludeProcesses Shows the processes in the True, False False
metadata tree.
MapAddedRowColumnStyle Sets the style to apply when NoStyle: No styles are NoStyle
you extend a Quick Report by applied to the extended
adding rows or columns. values
ServerStyle Apply server
styles to the extended values
LastRowColumnStyle: Apply
the style of the previous row
or column to the extended
cells
MapHotRefreshEnabled Enables the Use Type-in True, False False

Refresh option for Quick
Reports.
on or off by using the Use
Type-in Refresh option in the
Properties dialog box for
Quick Reports.
MapUseMergeAreas Allows the user to use True, False False

merged cells along the axes
of Quick Reports.
PreserveFormulas Preserves user formulas in an True, False True
exploration or Quick Report
when you commit data.
Attention: If this
option is set to False,
any formulas that you
add to an Exploration
View or Quick Report
are discarded when
you commit data.
on or off by using the
Preserve user formulas
option in the Options dialog
box.
PromptUncommitted When you refresh, prompts True, False True

Changes you to confirm before
uncommitted changes are
lost.
RefreshOnExcelHotkeys Refreshes data on Excel True, False False
recalculation keys (F9, Shift
F9). User needs to restart
Excel after change.
RefreshOnWriteBack Refreshes data on writeback. None None
The user can define whether
Workbook: Refreshes data in
the data in the workbook or
the workbook on writeback.
worksheet is refreshed.
Worksheet: Refreshes data in
the worksheet on writeback.
SetEditorPreviewOn Shows set members in the True, False True

Selection pane (Hierarchy
mode) of the Subset Editor
instead of the set definition
(Definition mode).
You can toggle the display in
the Selection pane using the
View Set Contents and View
Set Definition buttons.
SetRebuildOptionOnSlice Sets the TM1RebuildOption True, False False

variable. This variable causes
the worksheets in the book to
be rebuilt on opening (which
forces a recalculation to
happen on each sheet in the
book).
UseGzipUpload Enables Gzip compression for True, False True
data uploaded to TM1.

Notices
This information was developed for products and services offered worldwide.
This material may be available from IBM in other languages. However, you may be required to own a copy of the
product or product version in that language in order to access it.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local
IBM representative for information on the products and services currently available in your area. Any reference to an
IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may
be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property
right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM
product, program, or service. This document may describe products, services, or features that are not included in the
Program or license entitlement that you have purchased.
IBM may have patents or pending patent applications covering subject matter described in this document. The
furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing,
to:
IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in
your country or send inquiries, in writing, to:
Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are
inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION
"AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement
may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the
information herein; these changes will be incorporated in new editions of the publication. IBM may make
improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without
notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner
serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any
obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of
information between independently created programs and other programs (including this one) and (ii) the mutual use
of the information which has been exchanged, should contact:
IBM Software Group

Attention: Licensing
3755 Riverside Dr.

Ottawa, ON
K1V 1B7
Canada
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a
fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under
terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in
other operating environments may vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on generally available systems.
Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of
this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm the
accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities
of non-IBM products should be addressed to the suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and
represent goals and objectives only.
This information is for planning purposes only. The information here is subject to change before the products described
become available.
This information contains examples of data and reports used in daily business operations. To illustrate them as
completely as possible, the examples include the names of individuals, companies, brands, and products. All of these
names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely
coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming techniques
on various operating platforms. You may copy, modify, and distribute these sample programs in any form without
payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to
the application programming interface for the operating platform for which the sample programs are written. These
examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability,
serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind.
IBM shall not be liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM
Corp. _enter the year or years_.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.
This Software Offering does not use cookies or other technologies to collect personally identifiable information.
Product Information
This document applies to IBM Planning Analytics 2.0.0 and may also apply to subsequent releases.
Copyright
Licensed Materials - Property of IBM
© Copyright IBM Corp. 2007, 2017.
210 Notices
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp.,
registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other
companies. A current list of IBM trademarks is available on the web in " Copyright and trademark information " at
www.ibm.com/legal/copytrade.shtml.
The following terms are trademarks or registered trademarks of other companies:
• Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United
States, other countries, or both.
• Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe
Systems Incorporated in the United States, and/or other countries.
• Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
• UNIX is a registered trademark of The Open Group in the United States and other countries.
• Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
Microsoft product screen shot(s) used with permission from Microsoft.
Notices 211
Index
Special Characters API functions (continued)

GetTuple 145
.NET Framework GetValue 139
troubleshooting 176 HTTPLogonCredentials 129
version 176 ID 147
.NET programmability support 176 Logoff 130
#NAME! 81 Logon 130
#VALUE! 81 Name 147
Publish 131
Quick Reports 142, 145, 148–150
A Rebuild 147, 151
access privileges, See security RebuildSpecification 147
action buttons Refresh 139, 148, 150
adding 120 RefreshAllData 132
appearance 125 RefreshAllDataAndFormat 132
copying 125 RefreshSelection 133
deleting 125 RefreshSheet 133
editing 125 Replace 148
mapping fields 122–124 RowHierarchies 148
navigating to a worksheet 121, 124 Select 149
overview 119 SetColumnSuppression 140
recalculating or rebuilding a worksheet 124 SetRowSuppression 140
renaming 125 SetSlicer 149
running a process 121, 124 SetSpecification 141
understanding processing 119 SetValue 141
add-ins SlicerHierarchies 150
TM1 Perspectives add-in 81 SuppressMessages 133
TM1 worksheet functions add-in 81 SwapRowsAndColumns 139
aggregation TraceLog 134
samples and time dimensions 185 Unlink 140
annotations, See comments UnlinkAllData 134
API UnlinkBook 135
Dynamic Report functions overview 150 UnlinkSelection 135
exploration functions overview 137 UnlinkSheet 135
global functions overview 128 UpdateServerUrl 135
importing automation macros 127 Wait 136
processing within VBA 151 application programming interface, See API
Quick Report functions overview 142 applications
API functions setting up startup 23
Clear 137, 142 asymmetrical Exploration Views
ClearAllData 128 layouts 48
ClearBook 128 attributes
ClearCache 129 modifying 83, 84
ClearSelection 129 retrieving 83
ClearSheet 129 authentication
ColumnHierarchies 142 forms-based authentication 24
Create 137, 143 logging on 16
CreateFromMDX 138, 144 Auto prompts 29, 32, 33
Cube 144 auto spread 30
DataSource 145 Automate_COI_Excel.vbs 152
Dynamic Reports 150, 151 Automate_COI.vbs 152
EnableIndents 145 AutomateServerURLSample.vbs 152
Error 133 automation
GetColumnSuppression 138 Appending information into the log file 133
GetReport 143, 146 applying zero-suppression 138
GetRowSuppression 138 Clearing a selection 129
GetSpecification 146 Clearing books 128, 136
clearing data values 128, 137
213
automation (continued) cache (continued)
Clearing Quick Reports 142 clearing in Planning Analytics for Microsoft Excel 24
Clearing sheets 129 calculations
clearing the cache 129 adding to Exploration Views 44, 51
Creating Exploration View 137, 138 capability assignments 68, 69
Creating QuickReports 143, 144 cell styles 48, 55
Defining subset and dimension properties 141 cell-based reports
disconnecting link to IBM Cognos server 134 clearing data 19
GetReport 143, 146 converting to snapshot 20
GetValue 139 displaying package 59, 105
logging errors 128 refreshing 19
logging off all the IBM Cognos servers 130 cells
logging on 130 annotating 78
overview 127 colors for sandbox data 71
Rebuilding Dynamic Reports 151 converting to snapshot 20
Refresh 139 displaying data source 59, 105
refreshing data 132 excluding from data spreading 73
Refreshing Dynamic Reports 150 grouping 50
refreshing formatting 132 Certificate Authority (CA)
Refreshing Quick Reports 148 unable to create trust relationship 178
Refreshing selections 133 changes
Refreshing sheets 133 committing to TM1 72
Replacing MDX 148 discarding sandbox data 71
Retrieving Quick Report specifications 146 previewing 72
Retrieving rebuild specifications 147 Clear (API function) 137, 142
running processes 22 Clear Cache (API function) 129
sample macro files 151 ClearAllData (API function) 128
security settings 127 ClearBook (API function) 128
Setting Quick Report slicer dimensions 149 ClearSelection (API function) 129
Setting zero-suppression 140 ClearSheet (API function) 129
SetValue 141 Cognos Analysis servers
suppressing alerts and messages 133 updating URLs 23
Swapping rows and columns 139 Cognos gateway
tracking activities and errors 134 modifying address 15
Unlinking books 135 Cognos Office Reporting TM1 add-in 81
Unlinking data 140 Cognos systems
Unlinking selections 135 changing 51, 105
Unlinking sheets 135 changing for Dynamic Reports 59
updating system URLs 135 changing for Quick Reports 56
using action buttons 119 modifying 15
CognosOfficeAutomationExample.bas 127, 151
CognosOfficeAutomationPPExample.bas 127, 151
B CognosOfficeMessageSuppressor.cls 127, 151
base data 70, 72 CognosOfficeReportingSettings.xml
Baselines sample 188 settings options for committing data 79
batch processing 127 CognosOfficeTM1.xll 81
BI reports CognosOfficeXLLSettings.xml 81
Exploration Views 40 ColumnHierarchies (API function) 142
lists 39 columns
blank columns calculated 44, 51
adding an Excel calculation 51 inserting in a Dynamic Report 59
inserting into Exploration Views 44 inserting into Exploration Views 44
inserting into lists 40 inserting into lists 40
blank rows limiting 46
adding an Excel calculation 51 nesting 44
inserting into Exploration Views 44 renaming 40
bottom or top values swapping with rows 45
viewing in TM1 Exploration Views 47 Com Add-in
BulkUploadAutoCommitValid 79 Excel workbook closes unexpectedly 177
comments
adding and editing 78
C CommitWithoutConfirmation 79
conditional formatting 51
cache
connections
clearing 129
214
connections (continued) DBR (continued)
adding 15 modifying a range 106
consolidation holds, See holds overview 82
content DBRA
automating 127 overview 83
context DBRW
defining with formulas 107 dragging members to modify 106
context area in Custom Report 64
using in TM1 Exploration Views 46 in formula-based reports 63
convert to formulas modifying 105
errors 175, 178 modifying a range 106
Create (API function) 137, 143 overview 83
CreateFromMDX (API function) 138, 144 DBS 84
CSV formats 50 DBSA 84
Cube (API function) 144 DBSS 85
cubes, See data sources DBSW 85
Custom Report DFRST 86
changing the system and data source 105 dimensional data sources
creating from Exploration Views 63 using in a list 168
creating manually 64 using in an Exploration View 165
modifying DBRW formulas 105 dimensions
Custom Reports nesting 44
clearing 19 retrieving names of 97
overview 9, 63 retrieving the first member 86
publishing 21 retrieving the number of levels 88
refreshing 19 retrieving the number of members 87
searching 18
DIMIX 86
D DIMNM 86
dashboards, See see workspaces DIMSIZ 87
data direct writeback method 68
base 70 direct writeback mode 70
clearing 19 DisableSandboxing parameter 70
committing to TM1 72, 78, 79 display count
converting to snapshot 20 limiting 26
discarding sandbox values 71 DNEXT 87
editing in a Quick Report 55 DNLEV 88
editing in a TM1 Exploration View 48 Double-click 33
editing in TM1 72 DPR-ERR-2079 error 177
finding 18 drop zones 5
private 70 DTYPE 88
refreshing 19 Dynamic Reports
restoring after clearing 19 changing context members 59
data source changing the system and data source 59
displaying for formulas cells 59, 105 collapsing rows 58
loading most recent 26 creating 57
refreshing 17 displaying data source 59, 105
data sources editing sets 58
changing 17, 51, 105 expanding rows 58
changing for Dynamic Reports 59 formatting 60–62
changing for Quick Reports 56 inserting columns 59
logging on 16 inserting rows 59
opening 16 overview 57
data spreading publishing 21, 62
clearing 74 rebuilding 57, 124
excluding cells 73 recreating 57
in TM1 reports 73 refreshing 19, 57, 124
methods 74 suppressing zeros 58
overview 73 TM1ELLIST 97
syntax 76, 77 TM1GLOBALSANDBOX 99
DataSource (API function) 145 TM1INFO 99
DBR TM1RPTELISCONSOLIDATED 99
dragging members to modify 106 TM1RPTELLEV 100
modifying 105 TM1RPTELLSEXPANDED 100
215
Dynamic Reports (continued) error messages (continued)
TM1RPTFILTER 100 ValueNotInPickList (243) 181
TM1RPTROW 101 errors
TM1RPTTITLE 102 resolving data commit errors 79
TM1RPTVIEW 103 examples
TTM1PRIMARYDB 99 logging on with VBA 151
Dynamic Reports Planning Analytics macros 151
overview 9 VBS scripts 152
dynamic sets, See sets expand direction 50
Expand direction 27
Expanding consolidated members 33
E expired sessions 177
ELCOMP 89 Exploration Views
ELCOMPN 89 converting 57
elements, See members layouts 48
ELISCOMP 90 relational data 165
ELISPAR 91 Exploration Views for BI
ELLEV 92 adding calculations 51
ELPAR 92 inserting rows and columns 44
ELPARN 93 nesting data 166
ELSEN 94 overview 40
ELWEIGHT 94 swapping rows and columns 45
Employee Satisfaction Workspace sample 187 Exploration Views for IBM Cognos Analytics
EnableIndents (API function) 145 adding calculations 44
enabling Exploration Views for Planning Analytics
AutoLogFile 128 overview 9
equal across leaves spreading method 74 Exploration Views for TM1
equal spreading method 74, 77 adding calculations 44, 51
error messages adding comments to cells 78
COI-ERR-2002 Block type is not valid 178 changing the system and data source 51
COI-ERR-2005 this version of Microsoft Office is not supported committing data 78
179 converting 52
COI-ERR-2006 This Microsoft Office product is not supported converting to formulas 63
179 converting to snapshot 20
COI-ERR-2008 Unable to retrieve from resources 179 creating from scratch 41
COI-ERR-2009 Unable to perform this operation because creating from views 40
Microsoft Excel is in Edit mode 179 drilling down 47
COI-ERR-2010 The name {0} is not valid. A name must not editing data 48
contain both a quote (") character and an apostrophe () filtering data 46
character 179 inserting members 41, 43
COI-ERR-2016 Worksheet protected, IBM Cognos styles cannot inserting rows and columns 44
be populated 179 limiting items 46
Convert to Formulas does not show value 175 nesting rows and columns 44
COR-ERR-2004 Axis specification is not valid 180 publishing 21
COR-ERR-2007 error retrieving from resources 180 renaming rows or columns 43
COR-ERR-2009 Name formula is not valid 180 reordering rows or columns 43
COR-ERR-2010 Formula is not valid 180 resolving data errors 79
COR-ERR-2011 Invalid range: Please enter a valid range for setting options 50
crosstab or list 180 setting options for committing data 79
COR-ERR-2013 exploration cannot be converted to formula sorting rows 45
based 180 spreading data 73
COR-ERR-2014 Due to Excel Worksheet Limitations the Results swapping rows and columns 45
May Be Truncated 180 viewing top or bottom values 47
COR-ERR-2015 The current exploration cannot be rendered at zero suppression 46
this location on the worksheet 180 explorations
COR-ERR-2016 Unable to retrieve package 181 changing the system and data source 51
Error: Exception from HRESULT:<location> 178 clearing data 19
Excel workbook closes unexpectedly 177 converting 52
IBM Cognos Office Fails to Initialize in Microsoft Office 176 converting to other report type 50
IBM Cognos Office unable to create trust relationship 178 converting to snapshot 20
Microsoft Office Excel does not open a workbook published copying and moving 21
from IBM Cognos Office 176 displaying the information area 51
Results have exceeded the Excel row or column limit 177 Dynamic Reports 57
This item cannot be expanded 177, 178 editing TM1 data 72
216
explorations (continued) I
Exploration Views 40
formula-based reports 63 IBM Cognos for Microsoft Office
lists 39, 50 firewall security rejection 177
Quick Reports 51 IBM Cognos Office
refreshing 19 failure to initialize in Microsoft Office 176
report types for Planning Analytics data 9 numbered error messages 178
spreading data (TM1) 73 security issues 178
supported Microsoft Office applications 179
troubleshooting opening published documents 176
F IBM pane
file size overview 5
reducing 24 IBM Planning Analytics for Microsoft Excel
file types numbered error messages 180
registering 176 IBM Planning Analytics tab
reregistering 176 showing or hiding 8
filters IBM Planning Analytics Workspace 21, 62
top or bottom values 47 IBM task pane
firewall security rejection 177 opening 7
font colors 71 IBM TM1
format definitions opening workbooks 17
applying 62 IBM TM1 Perspectives
creating 61 feature differences 11
format range 60–62 opening reports 13
formats upgrading action buttons 14, 37
CSV 50 ID (API function) 147
raw XML 50 If you would still like to use PMHub direct connections, you can
refreshing 19 enable the ‘AllowPMHubDirect’ setting in the
forms-based authentication 24 CommManagerSettings.xml file. reports
formula-based reports converting to snapshot 20
creating from views 63 index
displaying data source 59, 105 retrieving for a member 86
modifying SUBNM formulas 107 using to retrieve members 86
formulas information area 51
displaying data source 59, 105 installations
function editor 80, 105, 106 COM add-in 176
functions
TM1 80 K
Keep command 166
G keep-only 46
gateway address KEY_ERR 81
defining 15
GetColumnSuppression (API function) 138 L
GetReport (API function) 143, 146
GetRowSuppression (API function) 138 labels 50
GetSpecification (API function) 146 language 198
GetTuple (API function) 145 languages
GO Data Warehouse (analysis) package (samples) 187 troubleshooting pack subkeys 176
GO Data Warehouse (query) package (samples) 187 layouts
GO Sales (analysis) package 188 Exploration View 48
GO Sales (analysis) sample 188 leaf holds 77
GO Sales (query) package 189 Level based indents 37
growth percent spreading method 74, 77 levels
determining for members 92
finding the number of 88
H inserting 42
holds inserting members from multiple levels 42
applying to cells 73 lists
syntax 77 creating a sample list report 168
Horizontal Pagination sample 189 examples 168
HTTPLogonCredentials (API function) 129 refreshing 19
understanding 168
lists for BI
217
lists for BI (continued) Microsoft Excel
overview 39 clearing cell contents 19
lists for IBM Cognos Analytics conditional formatting 51
adding calculations 51 inserting calculations 51
zero suppression 40 refreshing content, troubleshooting 179
lists for Planning Analytics ribbon 7
overview 9 row and column restrictions, resolving 177, 178
lists for TM1 workbook closes unexpectedly 177
adding calculations 51 Microsoft Office documents
converting to snapshot 20 opening from TM1 17
creating from scratch 39 models
inserting columns 40 sample models and packages 185
inserting members 41
nesting columns 44
renaming columns 40
N
reordering columns 40 Name (API function) 147
zero suppression 40 named ranges
local cache, See cache TM1RPTFMTIDCOL 103
localization 198 TM1RPTFMTRNG 103
log files named sandboxes 68–70
enabling 24 nest
viewing 24 rows and columns 44
Logoff (API function) 130 nested
Logon (API function) 130 Exploration View layouts 48
nested cells
M setting label options for Exploration Views 50
nesting
Macro trust access 13 data in Exploration Views 166
macros No Data sample 189
importing 127 non-English operating system
sample files 151 troubleshooting .NET Framework 176
security 127 null suppression, See zero suppression
MapAddedRowColumnStyle 53
match title elements 123
MDX expressions 64
O
members options
adding to a Quick Report 53 setting for Planning Analytics for Microsoft Excel 23
adding to the context area 46 overview area 5
determining child members 90
determining level 92
determining name length 94 P
determining parents 91
package
determining the number of 87
displaying for formulas cells 59, 105
determining the number of parents 93
loading most recent 26
determining the type 88
refreshing 17, 19
determining weight 94
package information 30
inserting from multiple levels 42
packages
inserting in a TM1 exploration 41
changing 17, 51
inserting in a TM1 Exploration View 42, 43
GO Data Warehouse (analysis) 187
limiting 26, 46
GO Data Warehouse (query) 187
renaming 43
GO Sales (analysis) sample 188
reordering 43
logging on 16
replacing in a Quick Report 54
Sales and Marketing (Cube) 188
retrieving child members 89
percent calculations 44
retrieving parents 92
percent change spreading method 74, 77
retrieving the index 86
performance
retrieving the next 87
TM1 data sources 177
retrieving the number of 97
personal workspace capability 69
retrieving the number of children 89
Perspectives, See IBM TM1 Perspectives
retrieving using SUBNM 95
PIAs (Primary Interop Assemblies)
retrieving using the index 86
installing subkeys 176
searching for 18
Planning Analytics for Microsoft Excel
sorting by values 45
clearing cache 24
viewing top or bottom values 47
overview 5
218
Planning Analytics for Microsoft Excel (continued) relational data (continued)
setting preferences 23 Exploration Views 165
showing or hiding on the ribbon 8 relational data sources
starting 7 using in a list 168
Planning Analytics Workspace 55 using in an Exploration View 165
port number 15 repeat across leaves spreading method 74
preferences repeat spreading method 74, 77
setting for IBM Planning Analytics for Microsoft Excel 23 Replace (API function) 148
Primary Interop Assemblies (PIAs) 176 replacement system 23
private sets, See sets report samples 183
private workspace, See sandboxes report types
processes overview 8
running 22 reports
running with action buttons 121, 124 copying and moving 21
prompt values lists 168
report samples 189 opening and saving 17
proportional spread 30 running IBM Cognos for Microsoft Office reports after expired
proportional spreading method 74, 77 session 177
public sets, See sets securing 24
Publish (API function) 131 Return Quantity by Product Line sample 187
published documents Revenue Data Workspace sample 187
opening in Microsoft Office 176 ribbon
IBM Planning Analytics tab 5, 7
showing or hiding the IBM Planning Analytics tab 8
Q rollup calculations 44
Quick Report options RowHierarchies (API function) 148
double-clicking 56 rows
Quick Reports calculated 44, 51
adding comments to cells 78 editing set in a Dynamic Report 58
adding members 53 inserting in a Dynamic Report 59
automatic refreshing 54 inserting into Exploration Views 44
changing the system and data source 56 limiting 46
clearing data 19 nesting 44
committing data 79 sorting 45
converting 57 suppressing zeros 58
converting to snapshot 20 swapping with columns 45
copying and moving 21
creating 52 S
creating from views 52
deleting 55 Sales and Marketing (Cube) package (samples) 188
editing data 55 Sample Outdoors Company
overview 9, 51 databases, models, and packages 185
publishing 21, 55 samples 183
refreshing 19, 54 samples
regions 52 Baselines 188
replacing members 54 cubes 186
resolving data errors 79 database, models, and packages 185
setting options for committing data 79 Employee Satisfaction Workspace 187
spreading data 73 employees 185
type-in refresh 54 GO data warehouse 186
GO Data Warehouse (analysis) package 187
GO Data Warehouse (query) package 187
R GO Sales (analysis) package 188
raw XML 50 GO Sales (query) package 189
Rebuild(API function) 147, 151 GO Sales transactional database 186
RebuildSpecification (API function) 147 horizontal pagination 189
RECALC_0_0 81 No Data 189
Refresh (API function) 139, 141 packages 187
Refresh(API function) 148, 150 Return Quantity by Product Line 187
RefreshAllData (API function) 132 Revenue Data Workspace 187
RefreshAllDataAndFormat (API function) 132 Sales and Marketing (Cube) package 188
RefreshSelection (API function) 133 sales and marketing data 185
RefreshSheet (API function) 133 sandboxes
relational data capability assignment 69
219
sandboxes (continued) static, converting to 55
cell coloring 71 straight spreading method 74, 77
committing data 72 styles
configuring for TM1 worksheet functions 81 Dynamic Reports 61
consolidated values 71 SUBNM
direct writeback with named sandboxes 70 in Custom Report 64
direct writeback without named sandboxes 70 in formula-based reports 63
disabling for a TM1 server 70 modifying 107
leaf values 71 SUBSIZ 97
merging data 72 Sum 34
named 69 Sum context 33
overview 70 suppression
resetting values 71 in lists 40
scripts selection-based 46
sample VBS files 152 totals-based 46
search results SuppressMessages (API function) 133
limiting the number of items 26 swap
security rows and columns 45
clearing the local cache 24 SwapRowsAndColumns (API function) 139
privileges 39–41, 63 syntax
settings for automation 127 data spreading methods 76, 77
using forms-based authentication 24 holds 77
security issues 178 system
Select (API function) 149 loading most recent 26
selection-based suppression 46 system information 30
ServerMap 81 systems
servers changing 17, 51, 105
changing 17, 51, 105 changing for Dynamic Reports 59
changing for Dynamic Reports 59 changing for Quick Reports 56
changing for Quick Reports 56 logging on 16
logging on 16 opening a data source or package 16
updating URLs 23 updating URLs 23
set editor
opening for SUBNM formulas 107
SetColumnSuppression (API function) 140
T
SetRowSuppression (API function) 140 TABDIM 97
sets The Sample Outdoors Company 183
overview 64 The Sample Outdoors Company samples 183
retrieving members using SUBNM 95 TM1
retrieving the number of members 97 capability assignments 68
SetSlicer(API function) 149 TM1 data
SetSpecification (API function) 141 adding to Exploration Views 43
single signon filtering in Exploration Views 46
forms-based authentication 24 TM1 data sources
SiteMinder improve performance 177
API function in IBM Cognos 129 TM1 Perspectives, See IBM TM1 Perspectives
SlicerHierarchies (API function) 150 TM1 Perspectives add-in 81
snapshots 20 TM1 reports
sort order 45 Dynamic Reports 57
source tree Quick Reports 51
finding items 18 TM1 server
limiting the number of items 26 connection settings for worksheet functions 81
overview 5 opening workbooks 17
refreshing 17 publishing workbooks 21
searching 18 TM1 servers
synchronizing 59, 105 changing 105
spreading, See data spreading changing for Dynamic Reports 59
stacked changing for Quick Reports 56
Exploration View layouts 48 committing data 72
starting cell 31, 32 connecting 15
startup application disabling sandboxes 70
setting up 23 logging on 16
static data 134 updating URLs 23
static sets, See sets TM1 systems
220
TM1 systems (continued) TM1USER 103
changing 17 top or bottom values
logging on 16 viewing in TM1 Exploration Views 47
TM1 worksheet functions totals
configuration settings 81 expand direction 50
DBR 82 totals-based suppression 46
DBRA 83 TraceError (API function) 133
DBRW 83 TraceLog (API function) 134
DBS 84 troubleshooting
DBSA 84 enabling logging 24
DBSS 85 fixes
DBSW 85 getting 172
DFRST 86 getting fixes 172
DIMIX 86 identifying problems 171
DIMNM 86 TurboIntegrator processes
DIMSIZ 87 running with action buttons 121, 124
DNEXT 87 See also processes
DNLEV 88
DTYPE 88
ELCOMP 89
U
ELCOMPN 89 Uncommitted changes 29, 32, 33
ELISCOMP 90 understanding
ELISPAR 91 lists 168
ELLEV 92 Unlink (API function) 140
ELPAR 92 Unlink Book (API function) 135
ELPARN 93 UnlinkAllData (API function) 134
ELSEN 94 UnlinkSelection (API function) 135
ELWEIGHT 94 UnlinkSheet (API function) 135
enabling the add-in 81 UpdateServerUrl method 135
modifying 80, 106 URLs
modifying DBRW 105 for Cognos systems 15
modifying SUBNM 107 updating for servers 23
overview 80 user credentials
sandboxes 81 automating logon 129
SUBNM 95 users
SUBSIZ 97 retrieving the current 103
TABDIM 97 utilities
TM1ELLIST 97 update system URLs 23
TM1GLOBALSANDBOX 99
TM1INFO 99
TM1PRIMARYDB 99 V
TM1RPTELISCONSOLIDATED 99
values
TM1RPTELLEV 100
committing to TM1 72
TM1RPTELLSEXPANDED 100
editing in TM1 72
TM1RPTFILTER 100
sorting 45
TM1RPTROW 101
VBA
TM1RPTTITLE 102
examples 151
TM1RPTVIEW 103
VBS
TM1USER 103
sample scripts 152
troubleshooting 81
VIEW 104
VIEW 104
views
TM1ELLIST 97
converting to formulas 63
TM1GLOBALSANDBOX 99
creating Exploration Views from views 40
TM1INFO 99
defining in Dynamic Reports 103
TM1PRIMARYDB 99
Visual Basic for Applications, See VBA
TM1RPTELISCONSOLIDATED 99
Visual Basic Scripting, See VBS
TM1RPTELLEV 100
TM1RPTELLSEXPANDED 100
TM1RPTFILTER 100 W
TM1RPTFMTIDCOL 62, 103
TM1RPTFMTRNG 103 Wait (API function) 136
TM1RPTROW 101 workbooks
TM1RPTTITLE 102 converting to snapshot 20
TM1RPTVIEW 103 opening and saving 17
publishing to TM1 21
221
worksheet functions, See TM1 worksheet functions
worksheets
clearing content 19
copying and moving 21
navigating with action buttons 121, 124
recalculating with action buttons 124
workspaces
samples 187
writeback mode
capability assignment 69
overview 68
Z
zero suppression
in Exploration Views 46
in lists 40
zeros
suppressing 58
222
IBM®

Ug CXR

Uploaded by

Copyright:

Available Formats

Ug CXR

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Ug CXR

Uploaded by

Copyright:

Available Formats

Planning Analytics for Microsoft Excel

Chapter 1. What's new in IBM Planning Analytics for Microsoft Excel...................................... 1

Chapter 2. Get started........................................................................................................... 5

Chapter 3. Work with data and reports................................................................................. 15

Chapter 4. Set options......................................................................................................... 23

Chapter 5. Explore TM1 data................................................................................................ 39

Chapter 7. Action buttons.................................................................................................. 119

Chapter 8. IBM API............................................................................................................ 127

Chapter 9. Tutorials........................................................................................................... 153

Chapter 10. Examples and use cases.................................................................................. 165

Appendix A. Sample reports and packages......................................................................... 183

Appendix B. Accessibility features..................................................................................... 191

Appendix C. Rebrand Cognos Office Components................................................................197

Appendix D. Settings in the CognosOfficeReportingSettings.xml file....................................201

© Copyright IBM Corp. 2009, 2017 ix

2.0.25 - Feature updates, September 12, 2017

2.0.23 - Feature updates, July 21, 2017

2.0.22 - Feature updates, June 23, 2017

2.0.21 - Feature updates, June 2, 2017

2.0.20 - Feature updates, May 13, 2017

2.0.18 - Feature updates, April 8, 2017

2.0.0 - Feature updates, December 16, 2016

New branding, look and feel

© Copyright IBM Corp. 2009, 2017 1

Changed task pane

Improved support of IBM Cognos TM1 Perspectives features

Shared components with IBM Planning Analytics Workspace

Support for multiple hierarchies

2 Planning Analytics for Microsoft Excel Version 2.0.0 : User Guide

Support for security authentication modes

Add new connections from the Connect button

New API functions

New settings in the Options screen

Formula writeback is enabled by default

What's new in IBM Planning Analytics for Microsoft Excel 3

© Copyright IBM Corp. 2009, 2017 5

6 Planning Analytics for Microsoft Excel Version 2.0.0 : User Guide

Before you begin

Configure antivirus software

Set up connections for TM1 Rest APIs

Internet browser requirements

Upgrade existing workbooks

Start IBM Planning Analytics for Microsoft Excel

The IBM Planning Analytics tab

8 Planning Analytics for Microsoft Excel Version 2.0.0 : User Guide

Planning Analytics for Microsoft Excel report types

10 Planning Analytics for Microsoft Excel Version 2.0.0 : User Guide

Notes for IBM TM1 Perspectives users

12 Planning Analytics for Microsoft Excel Version 2.0.0 : User Guide

Enable trust access to the VBA project object model

Open an IBM TM1 Perspectives workbook

About this task

About this task

1. On the IBM Planning Analytics toolbar, click Options .

14 Planning Analytics for Microsoft Excel Version 2.0.0 : User Guide

Before you begin

1. On the IBM Planning Analytics toolbar, click Options .

© Copyright IBM Corp. 2009, 2017 15

Open a data source