Tip or Technique

Notes on Report Bursting in IBM

Cognos 8.3
Product(s): IBM Cognos 8.3 Business Intelligence
Area of Interest: Reporting
Notes on Report Bursting in IBM Cognos 8.3 2

Copyright
Copyright © 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC
is an IBM Company. While every attempt has been made to ensure that the
information in this document is accurate and complete, some typographical
errors or technical inaccuracies may exist. Cognos does not accept
responsibility for any kind of loss resulting from the use of information
contained in this document. This document shows the publication date. The
information contained in this document is subject to change without notice.
Any improvements or changes to the information contained in this document
will be documented in subsequent editions. This document contains
proprietary information of Cognos. All rights are reserved. No part of this
document may be copied, photocopied, reproduced, stored in a retrieval
system, transmitted in any form or by any means, or translated into another
language without the prior written consent of Cognos. Cognos and the
Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated)
in the United States and/or other countries. IBM and the IBM logo are
trademarks of International Business Machines Corporation in the United
States, or other countries, or both. All other names are trademarks or
registered trademarks of their respective companies. Information about
Cognos products can be found at www.cognos.com
This document is maintained by the Best Practices, Product and Technology
team. You can send comments, suggestions, and additions to
cscogpp@ca.ibm.com .

IBM Cognos Proprietary Information

Notes on Report Bursting in IBM Cognos 8.3 3

Contents
1 INTRODUCTION ............................................................................................ 4
1.1 PURPOSE ............................................................................................................4
1.2 APPLICABILITY .....................................................................................................4
2 BURSTING LIST REPORTS ............................................................................ 4
2.1 OPTION 1 - BURST USING ONE QUERY ........................................................................4
2.2 LIST OPTION 2 - BURST USING TWO QUERIES ...............................................................6
2.3 OPTION 3 MULTI-RECIPIENT EMAIL ADDRESSES .............................................................8
3 BURST A CROSSTAB ...................................................................................... 8
3.1 CROSSTAB OPTION 1 - BURST USING TWO QUERIES ........................................................8
3.2 CROSSTAB OPTION 2 - BURST USING THREE QUERIES ......................................................9
3.3 OPTION 3 MULTI-RECIPIENT EMAIL ADDRESSES ........................................................... 10
4 BURSTING MULTILINGUAL REPORTS......................................................... 10
5 BURSTING DIFFERENT REPORT FORMATS................................................. 10
6 CONCLUSION .............................................................................................. 10
APPENDIX A: TERMINOLOGY ................................................................................. 11

IBM Cognos Proprietary Information

Notes on Report Bursting in IBM Cognos 8.3 4

1 Introduction
1.1 Purpose
This document discusses how bursting operates in IBM Cognos 8.3 in several
scenarios. This information is designed to compliment the information found
in the Report Studio users’ guide.

1.2 Applicability
This document applies to IBM Cognos 8.3 Business Intelligence.

2 Bursting List1 Reports

We will examine three options to burst a simple example with a grouped List
report. The List query contains the information we wish to disseminate
including a grouped data item which determines which user gets which data.

We will imagine a report with sales information by Region. The report is

grouped on and will be burst on Region Code.

2.1 Option 1 - Burst using One Query

In this option, we will define a single query to be used for three purposes:
• As the List Query
• As the Burst Query
• As the Recipient Query

In this example, this query is named List Query.

List Query will have the following information:

Region Region Revenue Recipient
Code
NA North America $123 fred.smith@abc.com
NA North America $123 maggie.jones@abc.com
ER Europe $123 david.black@abc.com
ER Europe $123 jane.white@abc.com
OT Other $123 mary.doe@abc.com
OT Other $123 teddy.schmoe.abc.com

1
Or Repeater reports which also use an un-pivoted query.

IBM Cognos Proprietary Information

Notes on Report Bursting in IBM Cognos 8.3 5

Note that the inclusion of the Recipients causes the data to be duplicated for
each Recipient as indicated by the shading. Even in this simple example, we
have double the number of rows in query due to adding the recipients. This
has an impact on data retrieval but not on the process of bursting the query
layout query results. When generating the report output the burst key
information is grouped and the distinct burst keys are used to produce one
output file (or set of files if rendering in multiple formats) per burst key.

We configure the burst as so:

At run time, here is how this burst is executed.

1. The Burst Query (List Query) is run
2. For each Burst Group (Region Code) in the Burst Query, the
Recipients are available.
3. One Burst Instance (ex. PDF file) is created for each Burst Group
(Region Code) in the Burst Query and sent to the associated Recipient
Address(s).

The affect of this is that the Burst Query (List Query) is run once and we
work our way through the Burst Groups (Region Code) distributing to the
Recipients.

This option is ideally used when all or most Burst Groups are being sent to a
single Recipient so there is little or no duplication of data in the query.

IBM Cognos Proprietary Information

Notes on Report Bursting in IBM Cognos 8.3 6

Note that if the burst keys and recipients are stored in multiple tables then
the join between these tables will need to be processed to determine the
combined query results for the burst/recipient query.

2.2 List Option 2 - Burst using Two Queries

In this option, we will define two separate queries:
• List and Burst Query
o Used as both the List query and the Burst query
• Recipient Query
o Used as the Recipient Query

List and Burst Query contains the information we wish to disseminate

including the Region grouped data item on which we will determine which
user gets which data:
Region Code Region Revenue
NA North America $123
ER Europe $123
OT Other $123

Recipient Query contains the Recipient information. In our example,

Recipients are all email addresses. This query makes the association between
a Recipient(s) and a Burst Group (Region).
Region Code Recipient
NA fred.smith@abc.com
NA maggie.jones@abc.com
ER david.black@abc.com
ER jane.white@abc.com
OT mary.doe@abc.com
OT teddy.schmoe.abc.com

IBM Cognos Proprietary Information

Notes on Report Bursting in IBM Cognos 8.3 7

We configure the burst as so:

In order to link Region in the Burst Query and Region in the Recipient query,
the master-detail relationships specify [Region Code] -> [Region Code].

At run time, here is how this burst is executed.

1. The Burst Query (List and Burst Query) is run
2. For Burst Group (Region Code) in the Burst Query, we execute the
Burst Recipients query (Recipient Query) passing the Region Code as
a filter item (classic master-detail operation).
3. One Burst Instance (ex. PDF file) is created for each Burst Group
(Region Code) in the Burst Query and sent to the associated Recipient
Address(s).

The affect of this is that the Burst Query is run once and we work our way
through the Burst Groups (Region Codes) executing the Recipient Query once
for each Burst Group (Region Code).

This option has the advantage that it does not duplicate the data in List
Query. It is well suited to scenarios where each Burst Group will be sent to
more than one Recipient. As Recipient Query is run many times this approach
has the potential disadvantage that this may cause database load issues due
to multiple queries but also provides an advantage in that there is no join to
be processed between separate burst and recipient tables. However, as most
Recipient lists for each Burst Group are quite small, these queries will also
generally be small and therefore have a light impact on the database.

IBM Cognos Proprietary Information

Notes on Report Bursting in IBM Cognos 8.3 8

2.3 Option 3 Multi-Recipient Email Addresses

A little known option is to specify multiple recipients in a single row of the
Recipient Query. This is only supported for Recipient Type of Email.

Multiple email recipients are separated by commas in the Recipient data item.
This allows us to use Option 1 Single Query without the disadvantage of
duplicating the data or running multiple queries. Our query would appear as
so:
Region Region Revenue Recipient
Code
NA North America $123 fred.smith@abc.com, maggie.jones@abc.com
ER Europe $123 david.black@abc.com, jane.white@abc.com
OT Other $123 mary.doe@abc.com, teddy.schmoe.abc.com

This option is new in IBM Cognos 8.3.

3 Burst a Crosstab2
IBM Cognos 8 does not support bursting a crosstab query directly. Therefore,
separate Burst and Crosstab Queries must be used. We will discuss options
using two or three queries.

3.1 Crosstab Option 1 - Burst using Two Queries

Like the List Option 1, this option uses a single query for the Burst and
Recipient Query:

As the actual data is in the crosstab query, our Burst and Recipient query
need only contain the Burst Key (Region Code) and Recipient:
Region Region Recipient
Code
NA North America fred.smith@abc.com
NA North America maggie.jones@abc.com
ER Europe david.black@abc.com
ER Europe jane.white@abc.com
OT Other david.black@abc.com
OT Other jane.white@abc.com

2
Or chart queries, neither of which can be burst because a pivoted query cannot be
sectioned.

IBM Cognos Proprietary Information

Notes on Report Bursting in IBM Cognos 8.3 9

The crosstab query will contain the data. The crosstab query will be executed
once for each Burst Key. As the data is separated from the recipients, there
are no problems with duplicate data being returned in the Burst Query.

The crosstab query is executed once per distinct burst key.

3.2 Crosstab Option 2 - Burst using Three Queries

One can also use three queries. A master-detail relationship will be
established from the Burst Query to the crosstab query and to the Recipient
Query as so:

The burst query would contain the Burst Group (Region Code) and Label
(Region):
Region Code Region
NA North America
ER Europe
OT Other

The Recipient Query would contain the Burst Group and Recipient:
Region Recipient
NA fred.smith@abc.com
NA maggie.jones@abc.com
ER david.black@abc.com
OT david.black@abc.com
OT jane.white@abc.com

The Crosstab Query is the same.

There is no distinct advantage to this approach and there is a drawback in

that the Recipient Query will now be submitted many times (once per burst
group).

IBM Cognos Proprietary Information

Notes on Report Bursting in IBM Cognos 8.3 10

3.3 Option 3 Multi-Recipient Email Addresses

This operates the same in both list and crosstab queries.

Again, for a Recipient Type of Email, multiple recipients can be defined in a

single row when the email recipients are separated by a comma. This allows
us to use the two-query approach of Option 1 for crosstabs. The burst and
recipient query would then look like:

Region Code Region Recipient

NA North America fred.smith@abc.com, maggie.jones@abc.com
ER Europe david.black@abc.com, jane.white@abc.com
OT Other mary.doe@abc.com, teddy.schmoe.abc.com

This option is new in IBM Cognos 8.3.

4 Bursting Multilingual Reports

Each burst report execution runs within a single language (locale). Therefore,
to burst a report in several languages it must be run in each language. This is
done by scheduling the report and selecting the required languages. Note
that the report is run (and burst) for each language selected.

Within the report itself, it is also necessary to filter the recipients by

language. This requires the additional of a language code to the Recipient
information and a filter on the Recipient Query. The Locale() function can be
used to return the current language for filtering purposes.

5 Bursting Different Report Formats3

Most report formats, PDF, HTML and Excel, are rendered based on the report
layout specified by the author. CSV and XML are based on the data.
Therefore, when bursting to a combination of layout and data based formats
the report will be run twice to create the required layouts.

6 Conclusion
There are several options for bursting; the information is this document is
designed to allow you need to choose the option that best meets your needs.

3
A product defect in the IBM Cognos 8.3 initial release returns an ‘unsupported’ error when
trying to burst CSV or XML. This is being addressed in a hot site update and in the first
service pack. Contact Customer Support for assistance with this issue.

IBM Cognos Proprietary Information

Notes on Report Bursting in IBM Cognos 8.3 11

Appendix A: Terminology
Burst Group – the report grouping item to be used to create Burst Instances
ex. Region Code

Burst Instance – a report result such as a PDF document with selected data
to be distributed to the Burst Recipients

Burst Recipient – the IBM Cognos 8 user or email address to which the Burst
Instance are available or sent

Burst Query – the query which drives the burst processing. This query
contains the Burst Group data item. For lists, this is often the same query
referenced by the list. As crosstab queries cannot be burst directly, the Burst
Query is a list query used as a master to the crosstab detail query.

Recipient Query – the query which contains the Burst Recipient information.
This is often the same query as the Burst Query.

Recipient Data Item – the data item in the Recipient Query containing the
Email address or CAMID of the Recipient.

Burst Master-Detail – used to link the Burst Query and the Recipient Query

Burst Label – the data item used to provide a name for the Burst Instances
ex. a report burst by Region Code might have a Burst Label of Region

IBM Cognos Proprietary Information