Proven Practice

Approach To The Cognos 8 SDK

Product(s): Cognos 8
Area of Interest: Development
Approach To The Cognos 8 SDK 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
[email protected] .

Cognos Proprietary Information

Approach To The Cognos 8 SDK 3

Contents
1 INTRODUCTION ............................................................................................ 4
1.1 PURPOSE .............................................................................................................. 4
1.2 APPLICABILITY ....................................................................................................... 5
1.3 EXCLUSIONS AND EXCEPTIONS .................................................................................... 5
2 GET THE RIGHT TOOLS FOR THE JOB ........................................................... 5
3 ABOUT COGNOS 8 WEB SERVICES................................................................ 6
4 DEPLOY A STANDALONE COGNOS 8 INSTALLATION.................................... 6
5 GO SALES AND RETAILERS ........................................................................... 7
6 CONTENT STORE LAYOUT AND SEARCH PATHS ........................................... 7
7 ENUMERATION SETS..................................................................................... 9
8 ALL THOSE CLASSES ................................................................................... 10
8.1 CLASSES THAT REPRESENT CONTENT STORE OBJECTS ...................................................... 10
8.2 CLASSES THAT IMPLEMENT PROPERTIES OF CONTENT STORE OBJECTS .................................. 11
9 THE COGNOS 8 SERVICES........................................................................... 11
10 LOGGING ON AND LOGGING OFF ............................................................... 12
10.1 LOGGING ON ....................................................................................................... 13
10.2 SHARING THE CAM PASSPORT BETWEEN SERVICES ........................................................ 14
10.2.1 Java Samples ................................................................................................ 14
10.2.2 C# Samples .................................................................................................. 15
10.3 LOGGING OFF ...................................................................................................... 15
10.4 FOR MORE INFORMATION........................................................................................ 15
11 QUERY THE CONTENT STORE ..................................................................... 15
11.1 THE CONTENTMANAGERSERVICE.QUERY () METHOD ....................................................... 16
11.2 HOW CONTENT STORE OBJECTS ARE RETURNED ........................................................... 16
11.3 FOR MORE INFORMATION........................................................................................ 17
12 RUNNING A SIMPLE REPORT...................................................................... 17
12.1 THE REPORTSERVICE.RUN () METHOD ........................................................................ 18
12.2 THE ASYNCHRONOUS CONVERSATION ......................................................................... 20
12.3 HOW THE CONTENTS OF A REPORT ARE RETURNED ........................................................ 21
12.4 FOR MORE INFORMATION........................................................................................ 23
13 CONCLUSION .............................................................................................. 23

Cognos Proprietary Information

Approach To The Cognos 8 SDK 4

1 Introduction
1.1 Purpose
The Cognos 8 Software Development Kit (SDK) can be used to create
anything from simple utility applications to full-scale, highly complex
applications. Indeed, most of the functionality provided through Cognos
Connection can be re-created using the Cognos 8 SDK.

The Cognos 8 SDK documentation contains over 1700 pages in PDF form. In
addition to the documentation, there are code samples that are installed with
the SDK and a considerable number of Knowledge Base and SupportLink
articles related to the Cognos 8 SDK. For someone just starting out with the
Cognos 8 SDK, all of this information can be overwhelming and finding a
place to get started can be difficult.

The purpose of this document is to provide focus on the knowledge elements

that are essential for almost every Cognos 8 SDK application. Once
comfortable with these knowledge elements, it will be much easier to
navigate and pinpoint information in the Cognos 8 SDK documentation and to
quickly make sense of the many sample code fragments that are available.

This document will make numerous references to the Cognos 8 SDK

documentation but will not repeat what is in the product documentation
unless the information is required for the purpose of illustration.

The reader of this document is expected to have the following background,

• Some experience programming in Java, C# or VB.NET
• Completed and configured a single-machine install of Cognos 8
• Installed the SDK on the same machine as Cognos 8
• Deployed the GO Sales and Retailers samples
• An understanding on the functionality available through Cognos
Connection.

The topics that will be highlighted in this document are,

• Content Store Structure and Search Paths
• Enumeration Sets
• Classes and Properties
• The Cognos 8 Services
• Logging On And Logging Off
• Querying the Content Store
• Running a Simple Report
• Introduction to the Asynchronous Conversation

Cognos Proprietary Information

Approach To The Cognos 8 SDK 5

Topics that will not be covered in this document but will be mentioned here
to alert the reader about what is possible with the Cognos 8 SDK are,
• Adding, deleting, modifying objects in the Content Store
• Running complex reports that require prompting
• Scheduling reports and running jobs
• Cognos 8 services other than the Content Manager Service and the
Report Service

In the Cognos 8 SDK documentation set, there are separate manuals for
developing Framework Manager metadata models and developing Custom
Authentication Providers. These are topics that require advanced knowledge
and are outside the scope of this document.

To create applications with the Cognos 8 SDK, it is not necessary to be an

expert in creating reports or data modelling. However, it is useful to know the
basics of both reporting and modelling. These basics can be obtained from
the samples and product documentation provided with Cognos 8 or from
courses offered by Cognos Global Education Services
(http://support.cognos.com/en/training/index.html?lid=//Services//Training).

1.2 Applicability
This document applies to the Cognos 8 SDK. The Cognos ReportNet SDK will
not be covered in this document. While much of the material in this
document does apply, there are differences between the Cognos 8 SDK and
the Cognos ReportNet SDK. The Cognos Proven Practices document titled
Approaching The CRN SDK has been created to address the specific topics of
the Cognos ReportNet SDK.

1.3 Exclusions and Exceptions

None at this time.

2 Get the Right Tools for the Job

Before beginning, it is strongly recommended that an IDE (Integrated
Development Environment) be obtained for the preferred programming
language. An IDE offers many things but such features as context sensitive
help, build and debugging facilities, real-time syntax checking and code
coloring are amongst the most useful.

If the intent is to write Cognos 8 SDK applications in Java, the Eclipse or

NetBeans IDEs are the most widely used and both are free. However, there
are other Java IDEs available and Cognos does not endorse one IDE over
another.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 6

The .NET Languages (C# and VB.NET) use Microsoft’s Visual Studio (VS) as
the IDE. As of January 2006, VS 2005 was the latest release and either the
“Standard” or “Professional” editions can be used.

If the intent is to use Visual Basic 6 as the development language, it is

strongly recommended that this be reconsidered and VB.NET be used
instead. The languages are not significantly different and the learning curve is
not steep. VB 6 is nearing the end of its product lifecycle and will soon be
considered unsupported by Microsoft. Please refer to lifecycle documentation
provided by Microsoft for information on end of life dates
(http://support.microsoft.com/gp/lifepolicy).

Once the preferred programming language is chosen, it is important to read

the relevant information contained in the section titled Cognos 8 Toolkits in
Chapter 1 of the Cognos 8 SDK Getting Started Guide.

3 About Cognos 8 Web Services

Cognos 8 is built using an architecture based on Web Services and the
Cognos 8 SDK is implemented on top of these Web Services. In practice,
there is no need to be concerned with the nuts and bolts of the Cognos 8
Web Services. It is safe to say that they work as advertised. If there is
interest in what the web services actually look like, there are numerous tools
available that allow SOAP messages to be viewed.

4 Deploy a Standalone Cognos 8 Installation

When starting out with the Cognos 8 SDK, it is recommended that a
standalone sandbox or development system be constructed for the first
stages of development. This will protect other installations of Cognos 8 from
potential errors that are a result of the initial learning curve.

In the standalone Cognos 8 installation, it is recommended to allow

unrestricted access to all objects in the Content Store. This is to eliminate the
need to consider access permissions while learning the core topics. This is not
to say that access permissions are not important but their use and
implications can be applied incrementally.

Setting up unrestricted access to the Content Store is done by specifying

individual Account or Group objects as members in the built-in System
Administrators role in the Cognos namespace. As will be discussed later, a
Cognos 8 SDK application gains access by logging on as a user in the same
manner as an interactive user. If that user that is a member of the built-in
System Administrators role, the Cognos 8 SDK application will have full access
to all objects in the Content Store.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 7

A default installation on a single server will allow Anonymous access and will
give the Everyone group in the Cognos namespace the permissions of the
built in System Administrators role. The Cognos 8 SDK application will not
need to logon as it will be treated as the Anonymous user.

If Anonymous access is not possible or desired then add a user from a

security namespace, which was setup during the installation process, to the
members of the System Administrators role. The Cognos 8 SDK application
will need to use this user account to authenticate and logon to Cognos 8.

5 GO Sales and Retailers

It is strongly recommended that the GO Sales and Retailers samples be
installed before using the Cognos 8 SDK. The GO Sales and Retailers samples
create a standalone reporting environment and provide the following benefits
for Cognos 8 SDK application development

• Populates the Content Store with sample reports with various styles
and complexities
• Referred to in the Cognos 8 SDK documentation
• Used by most code samples
• Is a “well-known” reporting environment with which many people are
already familiar
• Allows for easier replication of the reporting environment within
Cognos Support should assistance be required.

It is also recommended that some of the GO Sales and Retailers sample

reports be executed through Cognos Connection in order to get some
understanding on what is possible when running and managing reports. All of
the specific functionality related to running and managing reports through
Cognos Connection is available through the Cognos 8 SDK.

6 Content Store Layout and Search Paths

The objects that the Cognos 8 SDK works with are contained in the Content
Store under a hierarchical structure similar to nested folders and files. In
order to access these objects, one needs to be familiar with the layout of the
Content Store. You can find the layout of the Content Store in the Cognos 8
SDK Developer’s Guide under the section Content Store Structure within the
chapter Managing Content.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 8

The layout of the Content Store defines the search path. The search path is a
key component in developing Cognos 8 SDK applications as it is used to
identify which Content Store object(s) to retrieve. The Appendix titled Search
Path Syntax in the Cognos 8 SDK Developer’s guide provides detailed
information on search paths, including how to obtain a search path to an
individual object using Cognos Connection. In this section there is also a
short table that contains various search path samples. From this table, pay
particular attention to the meaning of “~”, “/” (single slash), “//” (double
slash) and”//*” (double slash and asterisk).

• A “~” (single tilde) is a shortcut to the search path that represents the
Account object of the user that the Cognos 8 SDK application is using
for authentication. More information on logging in a Cognos 8 SDK
application is covered later in this document.
• A “/” (single slash) in the search path means “return direct children”
of the specified type from the current location.
• A “//” (double slash) in the search means “return everything of the
specified type” from the current location
• A “//*” (double slash and asterisk) in the search path means “return
everything of any type” from the current location

A search path is similar to an XPath statement and the details on this topic
can be found in Appendix G of the Cognos 8 SDK Developer’s Guide. If
unfamiliar with XPath, it may be useful to review the basic concepts and an
introductory tutorial can be found at http://www.w3schools.com/xpath. There
is no need to be an expert in XPath to use the Cognos 8 SDK but it is worth
pointing out that using XPath to parse and process any XML document can
greatly simplify development by reducing the amount of code required within
an application.

In addition to their role in developing Cognos 8 SDK applications, search

paths are also used for other non-SDK purposes such as,
• Running a report via URL, independent of Cognos Connection
• Referencing user accounts and directory listings when bursting reports

In the Content Store hierarchy of Cognos 8, there are 7 top level folders.
They are,
• adminFolder
• capability
• configuration
• content
• directory
• portal
• transientStateFolder

Cognos Proprietary Information

Approach To The Cognos 8 SDK 9

The most widely used top level folders of a Cognos 8 SDK application will be
content and directory. In particular, the following sub-folders.
• /content/package will contain all of the reports and report views
created against a particular package.
• /directory/namespace will contain the external security information
such as users, groups and roles for a particular namespace. It is
important to note that with the exception of the built-in Cognos
namespace, the information contained here is not the actual data
stored in the external security provider. It is a representation of the
associated data that is specific to the Cognos Content Store.

In the documentation for the Content Store layout, there are sections for
each top level folder that contain useful search paths. The section for the top
level folder directory contains search paths for the built-in objects of the
Cognos namespace.

Content Store objects under /directory/namespace (including namespace)

have a search path that is different than the rest of the Content Store
hierarchy. These objects will all have a search path that begins with the word
“CAMID”, which stands for Cognos Access Manager ID. A CAMID is a
complete search path in the same manner as “~”. A CAMID is an internal
representation and a Cognos 8 SDK application should not be dependent on
the individual components that make up a CAMID. There is no guarantee that
the format or content of CAMID will remain the same across product releases.

7 Enumeration Sets
In the context of the Cognos 8 SDK, an enumeration set can be considered as
a list of read-only constants. As standalone entities, enumeration sets don’t
have much value. Their sole purpose is to act as an identifier without having
to know the actual contents. The values in an enumeration set are typically
used to provide input to a method although there are situations where they
are useful to determine an output type.

An entity in an enumeration set is specified in the form,

enumSetName.enumMemberName

For example,
• To specify the defaultName member in the propEnum enumeration
set, use propEnum.defaultName.
• To specify the account member in the classEnum enumeration set,
use classEnum.account.

There are over 80 enumeration sets in the Cognos 8 SDK but familiarity with
only 7 of them are required at this point. They are,

Cognos Proprietary Information

Approach To The Cognos 8 SDK 10

• General Use
o classEnum
• Query The Content Store
o propEnum
• Running Reports
o runOptionEnum
o outputEncapsulationEnum
o outputFormatEnum
o asynchReplyStatusEnum
o asynchDetailReportStatusEnum

The complete list of enumeration sets can be found in the Cognos 8 SDK
Developer’s Guide under the chapter titled Enumeration Sets.

In the next section, it will be seen that classEnum and propEnum are also
useful as a reference in identifying the purpose of the many classes that
make up the Cognos 8 SDK.

8 All Those Classes

There are close to 500 classes that make up the Cognos 8 SDK. Each class is
listed and described in the Cognos 8 SDK Developers Guide under the chapter
titled Classes.

The Cognos 8 class list can be categorized into two distinct groups,
• Classes that represent Content Store objects
• Classes that implement properties of Content Store objects

8.1 Classes that represent Content Store objects

The classes that represent Content Store objects are the ones that a Cognos
8 SDK application will be concerned with the most. These are the same
classes that are seen in the Content Store layout. They are also defined in the
classEnum enumeration set.

In addition to the classes listed in classEnum, there are several other classes
whose sole purpose is to define common properties for other classes. These
classes are known as abstract classes. There are several abstract classes in
the Cognos 8 SDK but at this point the most relevant ones are,
• baseClass – defines properties that apply to every class in classEnum
and the classes listed below.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 11

• uiClass –defines properties that can be manipulated through Cognos

Connection. This class is inherited by many of the classes listed in
classEnum.
• baseReport – inherits from uiClass. Contains properties common to
running and managing reports.
• authoredReport. – inherits from baseReport. Contains properties that
are specific to a particular report. The report specification is a
property of this class.

The terms object and class are often used interchangeably. In this document,
the term class will be used as a definition and the term object will be used to
represent a physical instance of this definition. For example, the term report
object will refer to an actual Content Store object of class report. An object
can be accessed with a search path.

8.2 Classes that implement properties of Content Store objects

The rest of the classes in the chapter titled Classes in the Cognos 8 SDK
Developer’s Guide are classes that implement properties of Content Store
objects. In fact, all Cognos 8 SDK properties are implemented as classes.
With the Cognos 8 SDK, there is no such thing as a “simple” or “native” data
type such as int, string, or boolean. Instead, these data types are
implemented through the use of classes. For example,

• the class booleanProp represents a native boolean data type

• the class intProp represents a native int data type
• the class stringProp represents a native string data type.

The classes that represent properties can be found in the propEnum

enumeration set. There are over 300 classes that represent properties.

9 The Cognos 8 Services

The Cognos 8 services are an SDK application’s interface to the Cognos 8
server. As of Cognos 8 MR2, there are 15 implemented services and 4
reserved services.

Each Cognos 8 service is defined by a specific functional purpose. For

example, the ContentManagerService is used to access and manipulate the
Content Store, the ReportService contains functionality that ensures reports
are run and the JobService is responsible for running jobs.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 12

Internally, a Cognos 8 service may call another Cognos 8 service to perform a

part of that task. For example, if a job contains a report to be run, the
JobService will call the ReportService to run the report.

Each Cognos 8 service has associated methods and each one of these
methods are part of a method set. It is possible for several services to
contain the same method. For example, both the ReportService and
JobService contain the run() method. The ReportService will run reports and
the JobService will run jobs.

The remainder of this document will focus on the following two services,
• ContentManagerService
• ReportService

These two services are the most widely used services in a typical Cognos 8
installation and are used by an SDK application to logon and logoff, make
queries to the Content Store and run reports. Once familiar with them,
making use of other services such as the JobService should be reasonably
straightforward.

One Cognos 8 service that does need a specific mention at this point is the
CognosReportNetService. This service is provided as a compatibility mode for
SDK applications originally written for Cognos ReportNet and should not be
used to develop new Cognos 8 SDK applications.

For detailed information on the Cognos 8 services, the methods available to

each service and code samples on how to create and connect a Cognos 8
service, see the chapter titled Services in the Cognos 8 SDK Developer’s
Guide.

10 Logging On and Logging Off

When an SDK application creates an object that represents a Cognos 8
service, the service will be automatically connected to Cognos 8 service at the
URL specified during the creation of the object. The process to create and
connect a Cognos 8 service is the same regardless of the service being used.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 13

Unless Anonymous access is allowed, when a Cognos 8 SDK application is

connected to the Cognos 8 server the application has no implied rights or
access permissions. The Cognos 8 SDK application needs to login just as an
interactive user would login. If anonymous access is allowed, the Cognos 8
SDK application will be granted the same rights and permissions as the
Anonymous user from the Cognos namespace. For example, if anonymous
access is not allowed and a Cognos 8 SDK application does not login, an
exception will occur when the SDK application tries to perform an action such
as querying the content store or running a report.

All logons and logoffs are performed through the ContentManagerService

using the logon() and logoff() methods. None of the other Cognos 8
services can perform a logon or logoff operation.

10.1 Logging On
The logon() method of the ContentManagerService takes 2 parameters,
credentials and roles.

The credentials parameter is string of encoded XML whose format is

described in the class credentials under the chapter titled Classes of the
Cognos 8 SDK Developer’s Guide.

The XML for a basic credentials parameter looks as follows,

<credential>
<namespace>
namespace ID as specified in Cognos Configuration
</namespace>
<username>
username contained in namespace
</username>
<password>
password for username
</password>
</credential>

The roles parameter is used to specify search paths to role objects in the
Cognos namespace. The permissions of these role objects will be applied to
the user specified in the credentials. If no additional roles are required, this
parameter must be an empty array instead of null.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 14

10.2 Sharing the CAM Passport Between Services

If the logon was successful, the ContentManagerService becomes an
authenticated service and a string known as a CAM Passport will be sent back
to the SDK application in the BiBusHeader. When an SDK application creates
an object to represent a Cognos 8 service, that object will contain a property
called BIBusHeader. The BIBusHeader represents the SOAP header that is
used to communicate with the Cognos 8 server. Within the BIBusHeader, is a
property named CAM which in turn contains a property named CAMPassport.
The CAM Passport returned by the logon() method is stored in the
CAMPassport property.

Why is the CAM Passport important? In an SDK application, the CAM Passport
does not automatically propagate to other services that might be used within
the application. Since the ContentManagerService is the only service than can
logon and logoff, there needs to be ability to assign the CAM Passport to
other services that the SDK application might require (such as the
ReportService). This assignment is done simply by copying the BIBusHeader
of the ContentManagerService to the BIBusHeader of the other service,
thereby making that service an authenticated service.

The samples that are installed with the Cognos 8 SDK contain code that
demonstrate how to connect to a Cognos 8 service, how to logon using the
ContentManagerService and how to copy a BIBusHeader from the
ContentManagerService to another service.

10.2.1 Java Samples

The Java sample files that show how to logon and share a CAM Passport are,
• <install_location>/sdk/java/Common/CRNConnect.java
• <install_location>/sdk/java/Security/Logon.java

To connect to a Cognos 8 service, in CRNConnect.java see the method

connectToCognosServer(String CMURL). This is a utility method will
connect all of the Cognos 8 services to the same URL.

Once the service has been connected, the method quickLogon() in the file
Logon.java shows how to build the credentials in XML and call the logon()
method of the ContentManagerService.

To copy the BIBusHeader, see the method getReportService() in

CRNConnect.java. A closer inspection of CRNConnect.java will reveal several
methods of the form get____Service() where the “____” can be filled in
with a Cognos 8 service name. The process of copying the BIBusHeader from
the ContentManagerService to another Cognos 8 service is the same,
regardless of the service.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 15

10.2.2 C# Samples
The C# sample files that show how to logon and share a CAM Passport are,
• <install_location/sdk/csharp/SamplesCommon/SamplesConnect.cs
• <install_location/sdk/csharp/SamplesCommon/SamplesLogon.cs

As can be seen in SamplesConnect.cs, all that is required to connect to a

Cognos 8 service is to set the Url property of Cognos 8 service object.

Once the Cognos 8 service has been connected, the method

specificUserLogon() shows how to build the credentials in XML and call
the logon() method of the ContentManagerService.

To copy the BIBusHeader from the ContentManagerService to another

service, simply use the “=” operator as shown in the get methods that are
implemented at the end of SamplesConnect.cs.

10.3 Logging Off

An SDK application logs off using the logoff() method of the
ContentManagerService. There are no parameters for the logoff() method.

When the logoff() method is called, the CAM passport will be invalidated
by the Cognos 8 server. This means any other authenticated Cognos 8
service that was established by the SDK application is automatically logged
off. Any subsequent use of the CAM Passport from a saved BIBusHeader will
return a fault.

If an SDK application does not explicitly logoff, the session will remain active
until it is timed out. SDK applications should log out when processing is done.

10.4 For More Information

For examples related to anonymous access, establishing a session with the
ContentManagerService, logging on and logging off, refer to any of the
articles linked to in the Cognos Proven Practices document titled KB Docs -
Accessing And Manipulating The Content Store With The SDK.

11 Query the Content Store

At some point a typical Cognos 8 SDK application will need to look for one or
more Content Store objects. This is done using the ContentManagerService.
As mentioned earlier, the Content Store objects that can be retrieved are
those that are listed in the classEnum enumeration set and are specified
using a search path.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 16

11.1 The ContentManagerService.query () Method

The query(searchPath, properties, sortBy, options) method
of the ContentManagerService is used to retrieve objects from the Content
Store. Since more than one Content Store object an be returned, the query()
method returns an array of Content Store objects.

The parameters of the query() method are as follows,

• searchPath is a string that contains the search path to the Content
Store object.
• properties is an array of values taken from the propEnum
enumeration set that identify the properties to be returned with the
Content Store object.
• sortBy is an array of sort objects that determines how the returned
array is sorted. This document will not discuss this parameter but
even if it is not used, an empty sort object must be provided.
• options is a queryOptions object that provides various options on
how the data is processed. This document will not discuss this
parameter but even if it is not used, an empty queryOptions object
must be provided.

In many sample code fragments, you will see the query() method called as
follows,

query(searchPath, properties, new Sort[] {}, new QueryOptions())

Note that the sortBy and options parameters are not null. They are empty
instances of an object. If null values are supplied, an error (exception) will
occur.

This is essentially all there is to retrieving objects from the Content Store.
Most of the code in the Cognos 8 SDK application will involve processing the
properties of the retrieved Content Store object(s).

11.2 How Content Store Objects Are Returned

The return type of the query(searchPath, properties, sortBy,
options) method is an array of baseClass objects. However, this does not
mean that the array actually holds baseClass objects. The array actually holds
the Content Store objects in the class you are expecting. The reason for the
returned array being baseClass objects is that programming language (Java,
C#, VB.NET) requires that all members of the array be the same class and
the only class that applies to all Content Store objects is baseClass. To access
the Content Store object that is stored in the array as the class expected to
be returned, the object must be cast to its actual class. In most instances,
the actual class of the Content Store object returned will be known so it can
be cast directly.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 17

In cases where the returned class is not known, it may be necessary to

determine the class of the object in order to cast it properly. For example, a
searchPath that specifies the return of all Content Store objects under a
specific folder object could return a combination of report, reportView, folder
and URL objects. To determine the class of object returned, there are two
techniques that can be used.

The first technique is to use a language specific operator that will perform an
object level comparison. In Java, use the “instanceof” operator, for C# use
the “is” operator and for VB.NET use the “TypeOf” and “Is” combination.

The second technique is to compare the value of the objectClass property of

a baseClass object against a member in ClassEnum. For example,

if (baseClassObj.getObjectClass().getValue()== ClassEnum.Report)
{
<code to process a Report object>
}

if (baseClassObj.getObjectClass().getValue()== ClassEnum.ReportView)
{
<code to process a ReportView object>
}

if (baseClassObj.getObjectClass().getValue()== ClassEnum.Account)
{
<code to process an Account object>
}

11.3 For More Information

For numerous examples related to retrieving objects from the content store,
see the Cognos Proven Practices document titled KB Docs - Accessing And
Manipulating The Content Store With The SDK.

12 Running a Simple Report

This section will focus on reports that are created and saved using Report
Studio. However, it is important to realize that the same concepts apply
equally to reports created and saved with Query Studio. There are a few
minor differences between the two as outlined here,
• Report Studio saves report objects in the Content Store.
• Query Studio saves query objects in the Content Store.
• report and query objects have the same set of properties.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 18

When discussing Cognos 8 and reports, the term report specification (often
shortened to report spec) will be used often. A report specification is simply
an XML document that can be interpreted by Cognos 8 to generate a report.
The XML document has no meaning outside of Cognos 8. A report
specification contains a large amount of information and can be very
complex. The details of report specifications are beyond the scope of this
document but more information can be found in of the Cognos 8 SDK
Developer’s Guide under the chapters titled Using Report Specifications and
Report Specification Reference.

The terms report and report specification are sometimes used

interchangeably in conversations outside the context of a Cognos 8 SDK
application. However, in terms of the Cognos 8 SDK this usage is not correct.
A report is a Content Store object and is a member of the enumeration set
classEnum. A report specification is a property and is a member of the
enumeration set propEnum. As one might expect, the report specification is a
property of the report class.

The section titled Running Reports in Chapter 3 of the Cognos 8 SDK

Developer’s Guide contains information related to running reports.

12.1 The ReportService.run () Method

To run a report using the Cognos 8 SDK, the method run(objectPath,
parameterValues, options) of the ReportService is used. This method
will execute an XML report specification that has been previously saved to the
Content Store as part of a report or reportView object. The objectPath
parameter is a search path to a report or reportView object. This is the
method that gets invoked when a users clicks on a report or reportView
object in Cognos Connection.

The runSpecification(specification, parameterValues,

options) method will run an XML report specification which is passed via
the specification parameter. This method is best suited for those
situations where report specs are created in real-time and are not stored in
the Content Store. This is the method that is invoked by Report Studio and
Query Studio to run a report.

The parameterValues and options parameters are the same for both the
run() and runSpecification() methods. Both of these parameters
must be actual objects regardless of whether they are being used. A value of
null (or nothing) will generate an error (exception).

Cognos Proprietary Information

Approach To The Cognos 8 SDK 19

parameterValues is an array of ParameterValue objects. Each item in the

array maps to a prompt that is contained within the report. The intricacies of
prompt/parameter processing can be complex and are outside the scope of
this document.

options is an array of option objects. It should be noted that the option

object itself is an abstract object and is only used to define properties for
other objects to inherit. The list of actual options that apply to running a
report are contained in the enumeration set runOptionEnum..

Some of the most common run options are,

• outputFormat – specifies the type(s) of output to generate. The valid
output types are specified in the enumeration set outputFormatEnum.
• outputEncapsulation – specified where the output is stored. The valid
output encapsulations are specified in the enumeration set
outputEncapsulationEnum.
• prompt – specifies whether or not to generate prompt pages to satisfy
unresolved report parameters. Processing prompt pages and
submitting prompt values from an SDK application are outside the
scope of this document.
• primaryWaitThreshold – initial time, in seconds, to wait for the report
to finish before an asynchronous conversion begins. The
asynchronous conversation will be discussed in the next section.
• secondaryWaitThreshold – when an asynchronous conversation is in
progress, the amount of time, in seconds, to wait between status
checks.
• saveOutput – specifies if the report output should be saved in the
Content Store

As one might expect, the run() method will wait for the report to finish
running but it is important to point out it will not wait forever. The run option
primaryWaitThreshold specifies the maximum amount of time spent waiting
in the run() method. The default value is 7 seconds. If the report output is
not ready after this amount time, the run() method will complete and the
Cognos 8 SDK application will continue on with processing. Additional blocks
of code after the run() method may be required to handle long running
reports. This will be discussed in the next section on the asynchronous
conversation.

For the sake of completeness, there is also the runAt(startTime,

objectPath, parameterValues, options) method if the
EventManagementService. This method behaves the same as the
run(objectPath, parameterValues, options) method except a
time to run the report is specified in the startTime parameter and the
output is stored in the Content Store. The runAt() method is not covered
in this document.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 20

12.2 The Asynchronous Conversation

Reports can be very dynamic in nature and there are often many external
factors that determine the performance and presentation of the report. The
factors include such things as the amount of data being retrieved, the
amount of formatting that needs to be done to the report and keeping
communications sockets active. Each of these factors are also subject to the
influence of the number of users accessing the environment and the load
being placed on the hardware being used in the environment. With so many
variables it is impossible to know how long it will take to run any given
report. In addition to this, there are also product features such as interactive
reporting and prompting that will add to the complexity of generating a
report. In order for a Cognos 8 SDK application to run a report in such a
complex environment, the asynchronous conversation is used.

When first starting out with the Cognos 8 SDK, the asynchronous
conversation may be more confusing than any other topic but a thorough
understanding of the asynchronous conversation will likely be required for
production quality applications. It is also important to realize that the
asynchronous conversation does not just apply to running reports. It applies
to all of the other Cognos 8 services that implement the run() method.

An example of an application that makes extensive use of the asynchronous

conversation is the Cognos Viewer. Some of the more visible aspects of the
asynchronous conversation are the rotating hourglass that is used while
waiting for output, the presentation of prompt pages, the submitting of
prompt values and paging up and down in an HTML report.

The details on the asynchronous conversation are contained in the Cognos 8

SDK Developer’s Guide under the section titled Understanding the
Asynchronous Conversation in the chapter Running Tasks. This section
includes a typical asynchronous conversation to run a report.

Even simple reports that have no prompts may take a long time to run. This
is often the case when large amounts of data are present in the report. As
mentioned in the previous section, the primaryWaitThreshold is used to
determine the amount of time the run() method will wait for report output.
If this time expires and the report output is still not ready, then the Cognos 8
SDK application must wait and remain synchronized with the Cognos 8 server
until the output is ready. This is accomplished using the wait() method of
the ReportService. The Cognos 8 SDK application will remain in the wait()
method until the report output is ready or the amount of time specified by
the run option secondaryWaitThreshold has passed. The default value for the
secondaryWaitThreshold is 30 seconds. A Cognos 8 SDK application will
generally just loop around the wait() method until the report output is
ready.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 21

The Cognos 8 SDK Developer’s Guide states that it is possible to set either of
the wait thresholds to 0. This means that there will be no asynchronous
conversation and the Cognos 8 SDK application will wait until report data is
returned or an error occurred. Waiting an indeterminate time is generally
considered to be a bad technique for production quality applications. This is a
passive approach and is difficult, if not impossible, to react to errors. In
addition, the application will usually require additional code to manage other
time-sensitive resources such as communications sockets. It is far better to
learn about and use the asynchronous conversation to actively manage the
processing of the report.

Setting a wait threshold to zero or a high value is acceptable for learning

purposes but is strongly discouraged for Cognos 8 SDK applications operating
in a production environment. All wait thresholds are specified in seconds.

12.3 How the Contents of a Report Are Returned

The run() method and the wait() method both return an asynchReply
object. An asynchReply object serves several purposes depending on the
state of the asynchronous conversation.

If the report is not complete, the asynchReply object is used primarily as a

status tracker in the asynchronous conversation and will be updated by the
wait() method.

If the report is complete, the details property of the asynchReply object will
contain an asynchDetailReportOutput object. Depending on the some of the
run options, the asynchDetailReportOutput object will either contain the
actual report output or a search path to where the output has been saved in
the Content Store.

The run options saveOutput, outputFormat and outputEncapsulation are the

main drivers of where report output is stored and how the Cognos 8 SDK
application will need to go about accessing this output.

If therun option saveOutput is true, then,

• The run option outputEncapuslation is ignored.
• One or more output formats can be specified.
• The report output will be stored in the Content Store as part of a
reportVersion object.
• The reportVersion object will be named with a timestamp and will be
a child object of the report object that was run.
• This reportVersion object will contain one or more child output
objects. One output object will be created for each output format
specified in the outputFormat run option.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 22

• The list of output objects is obtained with the getOutputObjects()

method of asynchDetailReportOutput.

Note that the runSpecification() method cannot have saved output

since there is no corresponding report object in the Content Store that can
contain the reportVersion object created to hold the saved output.

If the run option saveOutput is false, then,

• If multiple output formats are specified, an error (exception) will be
generated and the report will not be run.
• The report output may be stored depending on the value of the run
option outputEncapsulation.
o OutputEncapsulationEnum.none
ƒ the output will be returned in the
asynchDetailReportOutput object and can be accessed
with the getOutputPages() method.
o OutputEncapsulationEnum.URL
ƒ The getOutputPages() method of the
asynchDetailReportOutput object will contain a URL
that points to the report output.
ƒ In addition, the getOutputObjects() method of the
asynchDetailReportOutput object will contain a
complete search path to a temporary Content Store
object that holds the report output.
o OutputEncapsulationEnum.URLQueryString
ƒ The getOutputPages() method of the
asynchDetailReportOutput object will contain only the
query string of a URL. The query string of a URL is
everything that follows the “?” that is often seen after
the URL’s path component.
ƒ In addition, the getOutputObjects() method of the
asynchDetailReportOutput object will contain a
complete search path to a temporary Content Store
object that holds the report output.
o OutputEncapsulationEnum.HTML
ƒ The HTML output can be accessed with the
getOutputPages() method asynchDetailReportOutput
object. If the output format was HTML, then the actual
report output will be returned. If the output format was
not HTML, then an HTML page that references the
report output will be returned.

Cognos Proprietary Information

Approach To The Cognos 8 SDK 23

As can be seen from this list, specifying any of the outputEncapsulation

values except “none” will cause the report output to be stored in a temporary
Content Store object. If the report being run is large, not having the report
output stored could cause the Cognos 8 SDK application to run out of
memory as it attempts to retrieve the report output all at once. If the report
output is placed in the Content Store, it is possible to query the Content Store
object and retrieve the output in smaller chunks.

12.4 For More Information

This section should provide a basic foundation for running reports and
retrieving output. For numerous examples related to running reports, see the
Cognos Proven Practices document titled KB Docs - Reporting Using The SDK.

13 Conclusion
The information in this document should provide a basic foundation for the
Cognos 8 SDK. Using this foundation, there should be little problem in
navigating the entire Cognos 8 SDK documentation set and making use of
other Cognos 8 services to build robust SDK applications.

Cognos Proprietary Information