Approach to the IBM Cognos 8 SDK

21
Approach To The IBM Cognos 8 SDK Nature of Document: Tip or Technique Product(s): IBM Cognos 8 Area of Interest: Development Business Analytics

Transcript of Approach to the IBM Cognos 8 SDK

Page 1: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

Nature of Document: Tip or Technique

Product(s): IBM Cognos 8

Area of Interest: Development

Business Analytics

Page 2: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

Copyright and Trademarks Licensed Materials - Property of IBM.

© Copyright IBM Corp. 2010

IBM, the IBM logo, and Cognos are trademarks or registered trademarks of InternationalBusiness Machines Corp., registered in many jurisdictions worldwide. Other product andservice names might be trademarks of IBM or other companies. A current list of IBMtrademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml

While every attempt has been made to ensure that the information in this document isaccurate and complete, some typographical errors or technical inaccuracies may exist. IBMdoes not accept responsibility for any kind of loss resulting from the use of informationcontained in this document. The information contained in this document is subject to changewithout notice.

This document is maintained by the Best Practices, Product and Technology team. You cansend comments, suggestions, and additions to [email protected].

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of MicrosoftCorporation in the United States, other countries, or both.Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. inthe United States, other countries, or both.

Business Analytics

2

Page 3: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

Table of Contents1 Introduction .................................................................................................................. 4

1.1 Overview ...................................................................................................................... 4 1.2 Document Prerequisites ................................................................................................. 5 1.3 Scope of Document ....................................................................................................... 5

2 Get The Right Tools For The Job ..................................................................................... 5

3 About IBM Cognos 8 Web Services ................................................................................. 6

4 Deploy a Standalone IBM Cognos 8 Installation ............................................................... 6

5 Sample Deployments And Data ....................................................................................... 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 IBM Cognos 8 Services .......................................................................................... 11

10 Logging On and Logging Off ......................................................................................... 12

10.1 Logging On ................................................................................................................. 12 10.2 Sharing the CAM Passport Between Services .................................................................. 13 10.3 Logging Off ................................................................................................................. 14

11 Query the Content Store .............................................................................................. 15

11.1 The ContentManagerService.query () Method ................................................................ 15 11.2 How Content Store Objects Are Returned ...................................................................... 16

12 Running a Simple Report .............................................................................................. 17

12.1 The ReportService.run () Method .................................................................................. 17 12.2 The Asynchronous Conversation ................................................................................... 19 12.3 How the Contents of a Report Are Returned .................................................................. 20

13 For More Information ................................................................................................... 21

14 Conclusion ................................................................................................................... 22

Business Analytics

3

Page 4: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

1 Introduction

1.1 Overview

The IBM Cognos 8 Software Development Kit (SDK) can be used to create anything from simple utilityapplications to full-scale, highly complex applications. Indeed, most of the functionality providedthrough Cognos Connection can be re-created using the IBM Cognos 8 SDK.

As of version 8.4.1, the IBM Cognos 8 SDK documentation contains over 2900 pages in PDF form. Inaddition to the documentation, there are code samples that are installed with the SDK and aconsiderable number of Technotes and SupportLink articles related to the IBM Cognos 8 SDK. Forsomeone just starting out with the IBM Cognos 8 SDK, all of this information can be overwhelmingand 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 foralmost every IBM Cognos 8 SDK application. Once comfortable with these knowledge elements, it willbe much easier to navigate and pinpoint information in the IBM Cognos 8 SDK documentation and toquickly make sense of the many sample code fragments that are available.

This document will make numerous references to the IBM Cognos 8 SDK documentation but will notrepeat what is in the product documentation unless the information is required for the purpose ofillustration.

The topics that will be highlighted in this document are,

● Content Store Structure and Search Paths

● Enumeration Sets

● Classes and Properties

● The IBM Cognos 8 Services

● Logging On and Logging Off

● Querying the Content Store

● Running a Simple Report

● Introduction to the Asynchronous Conversation

Topics that will not be covered in this document but will be mentioned here to alert the reader aboutwhat is possible with the IBM Cognos 8 SDK are,

● Adding, deleting, modifying objects in the Content Store

● Running complex reports that require prompting

● Scheduling reports and running jobs

Business Analytics

4

Page 5: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

● IBM Cognos 8 services other than the Content Manager Service and the Report Service

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

To create applications with the IBM Cognos 8 SDK, it is not necessary to be an expert in creatingreports 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 IBMCognos 8 or from formal training courses offered by IBM Cognos Education. More information on theIBM Cognos Education training offerings can be found at http://www-01.ibm.com/software/data/education/cognos.html.

1.2 Document Prerequisites

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 IBM Cognos 8 BI

● Installed the SDK on the same machine as IBM Cognos 8 BI

● Installed and deployed some of the IBM Cognos 8 BI sample packages and data

● An understanding on the functionality available through IBM Cognos Connection.

1.3 Scope of Document

This concepts presented in this document applies to all versions of the IBM Cognos 8 SDK.

2 Get The Right Tools For The JobBefore beginning, it is strongly recommended that an Integrated Development Environment (IDE) beobtained for the preferred programming language. An IDE offers many things but such features ascontext sensitive help, build and debugging facilities, real-time syntax checking and code coloring areamongst the most useful.

If the intent is to write IBM Cognos 8 SDK applications in Java, the Eclipse IDE is widely used and canbe downloaded without cost from http://www.eclipse.org.

If writing IBM Cognos 8 SDK applications in C# or VB.NET, Microsoft’s Visual Studio is typically usedas the IDE. There are also no-cost open source IDEs available.

Business Analytics

5

Page 6: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

If the intent is to use Visual Basic 6 (VB6) as the development language, it is strongly recommendedthat this be reconsidered and VB.NET be used instead. In addition to VB6 being out of extendedsupport by Microsoft since April 2008, IBM Cognos 8 SDK support for VB6 has been deprecated withthe release of IBM Cognos 8 BI version 8.4.

Once the preferred programming language is chosen, it is important to read the relevant informationcontained in the section titled IBM Cognos 8 Toolkits in the IBM Cognos 8 SDK Getting Started Guide.

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

4 Deploy a Standalone IBM Cognos 8 InstallationWhen starting out with the IBM Cognos 8 SDK, it is recommended that a standalone sandbox ordevelopment system be constructed for the first stages of development. This will protect otherinstallations of IBM Cognos 8 from potential errors that are a result of the initial learning curve.

In the standalone IBM Cognos 8 installation, it is recommended to allow unrestricted access to allobjects in the Content Store. This is to eliminate the need to consider access permissions whilelearning the core topics. This is not to say that access permissions are not important but their use andimplications can be applied incrementally.

Setting up unrestricted access to the Content Store is done by specifying individual Account or Groupobjects as members in the built-in System Administrators role in the Cognos namespace. As will bediscussed later, an IBM Cognos 8 SDK application gains access by logging on as a user in the samemanner as an interactive user. If that user that is a member of the built-in System Administratorsrole, the IBM Cognos 8 SDK application will have full access to all objects in the Content Store.

A default installation on a single server will allow Anonymous access and will give the Everyone groupin the Cognos namespace the permissions of the built-in System Administrators role. The IBM Cognos8 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, whichwas setup during the installation process, to the members of the System Administrators role. The IBMCognos 8 SDK application will need to use this user account to authenticate and logon to IBM Cognos8.

Business Analytics

6

Page 7: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

5 Sample Deployments And DataIt is strongly recommended that some of the IBM Cognos 8 BI sample deployments and data beinstalled before using the IBM Cognos 8 SDK. This will create a standalone reporting environment andprovide the following benefits for IBM Cognos 8 SDK application development

● Populates the Content Store with sample reports with various styles and complexities

● Referred to in the IBM Cognos 8 SDK documentation

● Used by most SDK code samples

● Is a “well-known” reporting environment with which many people are already familiar

● Allows for easier replication of the reporting environment within IBM Cognos Support shouldassistance be required

It is also recommended that some of the sample reports be executed through IBM Cognos Connectionin order to get some understanding on what is possible when running and managing reports. All ofthe specific functionality related to running and managing reports through IBM Cognos Connection isavailable through the IBM Cognos 8 SDK.

6 Content Store Layout and Search PathsThe objects that the IBM Cognos 8 SDK works with are contained in the Content Store under ahierarchical structure similar to nested folders and files. In order to access these objects, one needsto be familiar with the layout of the Content Store. You can find the layout of the Content Store in theIBM Cognos 8 SDK Developer’s Guide.

● For IBM Cognos 8 BI versions 8.1, 8.2 and 8.3 see the section Content Store Structurewithin the chapter Managing Content.

● For IBM Cognos 8 BI version 8.4 see Appendix C – Initial Content Store Settings.

The layout of the Content Store defines the search path. The search path is a key component indeveloping IBM Cognos 8 SDK applications as it is used to identify which Content Store object(s) toretrieve. The Appendix titled Search Path Syntax in the IBM Cognos 8 SDK Developer’s Guide providesdetailed information on search paths, including how to obtain a search path to an individual objectusing IBM Cognos Connection. In this section there is also a short table that contains various searchpath 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 theuser that the IBM Cognos 8 SDK application is using for authentication. More information onlogging in an IBM 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

Business Analytics

7

Page 8: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

from the current location.

● A “//” (double slash) in the search means “return everything of the specified type” from thecurrent 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. If unfamiliar with XPath, it may be useful to reviewthe 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 IBM Cognos 8 SDK but it is worth pointing outthat using XPath to parse and process any XML document can greatly simplify development byreducing the amount of code required within an application.

In the IBM Cognos 8 SDK Developer's Guide, the chapter Classes contains a section titled ContentManager Containment Relationships. This section is very useful as a quick reference guide todetermine where in the Content Store hierarchy an object resides and what the search path to theobject will be.

In addition to their role in developing Cognos 8 SDK applications, search paths are also used for othernon-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

The most widely used top level folders of a Cognos 8 SDK application will be content and directory. Inparticular, the following sub-folders.

● /content/package will contain all of the reports and report views created against a particularpackage.

● /directory/namespace will contain the external security information such as users, groupsand roles for a particular namespace. It is important to note that with the exception of the

Business Analytics

8

Page 9: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

built-in Cognos namespace, the information contained here is not the actual data stored inthe external security provider. It is a representation of the associated data that is specific tothe Content Store.

Content Store objects under /directory/namespace (including namespace) have a search path that isdifferent than the rest of the Content Store hierarchy. These objects will all have a search path thatbegins with the word “CAMID”, which stands for Cognos Access Manager ID. A CAMID is a completesearch path in the same manner as “~”. A CAMID is an internal representation and an IBM Cognos 8SDK application should not be dependent on the individual components that make up a CAMID. Thereis no guarantee that the format or content of CAMID will remain the same across product releases.

7 Enumeration SetsIn the context of the IBM Cognos 8 SDK, an enumeration set can be considered as a list of read-onlyconstants. As standalone entities, enumeration sets don’t have much value. Their sole purpose is toact as an identifier without having to know the actual contents. The values in an enumeration set aretypically used to provide input to a method although there are situations where they are useful todetermine 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 many enumeration sets in the IBM Cognos 8 SDK (80+ in version 8.2 and 110+ in version8.4) but familiarity with only 7 of them are required at this point. They are,

● General Use

● classEnum

● Query The Content Store

● propEnum

● Running Reports

● runOptionEnum

● outputEncapsulationEnum

● outputFormatEnum

Business Analytics

9

Page 10: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

● asynchReplyStatusEnum

● asynchDetailReportStatusEnum

The complete list of enumeration sets can be found in the IBM Cognos 8 SDK Developer’s Guideunder the chapter titled Enumeration Sets. In the next section, it will be seen that classEnum andpropEnum are also useful as a reference in identifying the purpose of the many classes that make upthe Cognos 8 SDK.

8 All Those ClassesThere are several hundred classes that make up the IBM Cognos 8 SDK. Each class is listed anddescribed in the IBM Cognos 8 SDK Developers Guide under the chapter titled Classes.

The IBM 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 an IBM Cognos 8 SDK applicationwill be concerned with the most. These are the same classes that are seen in the Content Storelayout. 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 todefine common properties for other classes. These classes are known as abstract classes. There areseveral abstract classes in the IBM 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 listedbelow.

● uiClass – defines properties that can be manipulated through IBM Cognos Connection. Thisclass is inherited by many of the classes listed in classEnum.

● baseReport – inherits from uiClass. Contains properties common to running and managingreports.

● authoredReport. – inherits from baseReport. Contains properties that are specific to aparticular 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 beused 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. Anobject can be accessed with a search path.

Business Analytics

10

Page 11: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

8.2 Classes that implement properties of Content Store objects

The rest of the classes in the chapter titled Classes in the IBM Cognos 8 SDK Developer’s Guide areclasses that implement properties of Content Store objects. In fact, all IBM Cognos 8 SDK propertiesare implemented as classes. With the IBM 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 throughthe 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. In version 8.2there are over 300 classes that represent properties, in version 8.4 there are over 400.

9 The IBM Cognos 8 ServicesThe IBM Cognos 8 services are an SDK application’s interface to the IBM Cognos 8 server. Dependingon the version, there are 15 -20 services that can be used in an IBM Cognos 8 SDK application.

Each IBM Cognos 8 service is defined by a specific functional purpose. For example, theContentManagerService is used to access and manipulate the Content Store, the ReportServicecontains functionality that ensures reports are run and the JobService is responsible for running jobs.

Internally, an IBM Cognos 8 service may call another IBM Cognos 8 service to perform a part of thattask. For example, if a job contains a report to be run, the JobService will call the ReportService torun the report.

Each IBM Cognos 8 service has associated methods and each one of these methods are part of amethod set. It is possible for several services to contain the same method. For example, both theReportService and JobService contain the run() method. The ReportService will run reports and theJobService 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 IBM Cognos 8 installation and areused 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 reasonablystraightforward.

Business Analytics

11

Page 12: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

For detailed information on each of the IBM Cognos 8 services, the methods available to each serviceand code samples on how to create and connect to an IBM Cognos 8 service, see the chapter titledServices in the Cognos 8 SDK Developer’s Guide.

NOTE : In the IBM Cognos 8 SDK versions 8.1 and 8.2, there is a service namedCognosReportNetService. This service is provided for compatibility purposes for SDKapplications that were written for IBM Cognos ReportNet. The CognosReportNetService waslisted as deprecated with the release of version 8.1 and was removed from the product withversion 8.3.

10 Logging On and Logging OffWhen an IBM Cognos 8 SDK application creates an object that represents a IBM Cognos 8 service, theservice will be automatically connected to IBM Cognos 8 service at the URL specified during thecreation of the object. The process to create and connect a IBM Cognos 8 service is the sameregardless of the service being used.

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

All logons and logoffs are performed through the ContentManagerService by the logon() and logoff()methods. None of the other IBM 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 credentialsunder the chapter titled Classes of the IBM Cognos 8 SDK Developer’s Guide. The XML for a basiccredentials parameter looks as follows,

<credential><namespace>

namespace ID as specified in Cognos Configuration

</namespace><username>

username contained in namespace

</username>

Business Analytics

12

Page 13: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

<password>password for username

</password></credential>

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

10.2 Sharing the CAM Passport Between Services

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

Why is the CAM Passport important? In an IBM Cognos 8 SDK application, the CAM Passport does notautomatically propagate to other services that might be used within the application. Since theContentManagerService is the only service than can logon and logoff, there needs to be ability toassign the CAM Passport to other services that the SDK application might require (such as theReportService). This assignment is done simply by copying the BIBusHeader of theContentManagerService to the BIBusHeader of the other service, thereby making that service anauthenticated service.

The samples that are installed with the IBM Cognos 8 SDK contain code that demonstrate how toconnect to an IBM Cognos 8 service, how to logon using the ContentManagerService and how to copya BIBusHeader from the ContentManagerService to another service.

10.2.3 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 an IBM Cognos 8 service, in CRNConnect.java see one of the connectToCognosServermethods. This is a utility method that will connect many of the IBM Cognos 8 services to the sameURL. Once the IBM Cognos 8 service has been connected, the method quickLogon() in the file Logon.javashows how to build the credentials in XML and call the logon() method of the ContentManagerService.

Business Analytics

13

Page 14: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

To copy the BIBusHeader, see the method getReportService() in CRNConnect.java. A closerinspection of CRNConnect.java will reveal several methods of the form get____Service() where the“____” can be filled in with an IBM Cognos 8 service name. The process of copying the BIBusHeaderfrom the ContentManagerService to another IBM Cognos 8 service is the same, regardless of theservice.

10.2.4 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 an IBM Cognos 8 service is toset the Url property of IBM Cognos 8 service object. Once the Cognos 8 service has been connected, the method specificUserLogon() shows how to buildthe 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 IBM Cognos 8 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 IBM Cognos 8server. This means any other authenticated IBM Cognos 8 service that was established by the SDKapplication is automatically logged off. Any subsequent use of the CAM Passport from a savedBIBusHeader will return a fault.

If an IBM Cognos 8 SDK application does not explicitly log off, the session will remain active until it istimed out. All SDK applications that have logged in should log off when processing is done.

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

Business Analytics

14

Page 15: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

11.1 The ContentManagerService.query () Method

The query(searchPath, properties, sortBy, options) method of the ContentManagerService is usedto 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 theproperties to be returned with the Content Store object.

● sortBy is an array of sort objects that determines how the returned array is sorted. Thisdocument will not discuss this parameter but even if it is not used, an empty sort objectmust be provided.

● options is a queryOptions object that provides various options on how the data isprocessed. This document will not discuss this parameter but even if it is not used, anempty 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. Ifnull 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 IBMCognos 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 ofbaseClass objects. However, this does not mean that the array actually holds baseClass objects. Thearray actually holds the Content Store objects in the class you are expecting. The reason for thereturned array being baseClass objects is that programming language (Java, C#, VB.NET) requiresthat all members of the array be the same class and the only class that applies to all Content Storeobjects is baseClass. To access the Content Store object that is stored in the array as the classexpected to be returned, the object must be cast to its actual class. In most instances, the actualclass of the Content Store object returned will be known so it can be cast directly.

Business Analytics

15

Page 16: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

In cases where the returned class is not known, it may be necessary to determine the class of theobject in order to cast it properly. For example, a searchPath that specifies the return of all ContentStore objects under a specific folder object could return a combination of report, reportView, folderand URL objects. To determine the class of object returned, there are two techniques that can beused.

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 andIs combination.

The second technique is to compare the value of the objectClass property of a baseClass objectagainst 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>

}

12 Running a Simple ReportThis section will focus on reports that are created and saved using Report Studio. However, it isimportant to realize that the same concepts apply equally to reports created and saved with QueryStudio. 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.

Business Analytics

16

Page 17: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

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

The terms report and report specification are sometimes used interchangeably in conversationsoutside the context of a IBM Cognos 8 SDK application. However, in terms of the IBM Cognos 8 SDKthis usage is not correct. A report is a Content Store object and is a member of the enumeration setclassEnum. A report specification is a property and is a member of the enumeration set propEnum. Asone might expect, the report specification is a property of the report class.

The section titled Running Reports in the IBM Cognos 8 SDK Developer’s Guide contains informationrelated to running reports.

12.1 The ReportService.run () Method

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

The runSpecification(specification, parameterValues, options) method will run an XML reportspecification which is passed via the specification parameter. This method is best suited for thosesituations where report specs are created in real-time and are not stored in the Content Store. This isthe 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 beingused. A value of null (or nothing) will generate an error (exception).

parameterValues is an array of ParameterValue objects. Each item in the array maps to a prompt thatis contained within the report. The intricacies of prompt/parameter processing can be complex andare outside the scope of this document.

options is an array of option objects. It should be noted that the option object itself is an abstractobject and is only used to define properties for other objects to inherit. The list of actual options thatapply to running a report are contained in the enumeration set runOptionEnum.

Some of the most common run options are,

Business Analytics

17

Page 18: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

● outputFormat – specifies the type(s) of output to generate. The valid output types arespecified in the enumeration set outputFormatEnum.

● outputEncapsulation – specified where the output is stored. The valid output encapsulationsare specified in the enumeration set outputEncapsulationEnum.

● prompt – specifies whether or not to generate prompt pages to satisfy unresolved reportparameters. Processing prompt pages and submitting prompt values from an SDKapplication are outside the scope of this document.

● primaryWaitThreshold – initial time, in seconds, to wait for the report to finish before anasynchronous conversion begins. The asynchronous conversation will be discussed in thenext section.

● secondaryWaitThreshold – when an asynchronous conversation is in progress, the amountof 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 topoint out it will not wait forever. The run option primaryWaitThreshold specifies the maximum amountof time spent waiting in the run() method. The default value is 7 seconds. If the report output is notready after this amount time, the run() method will complete and the IBM Cognos 8 SDK applicationwill continue on with processing. Additional blocks of code after the run() method may be required tohandle long running reports. This will be discussed in the next section on the asynchronousconversation.

For the sake of completeness, there is also the runAt(startTime, objectPath, parameterValues,options) method of the EventManagementService. This method behaves the same as the run(objectPath, parameterValues, options) method except a time to run the report is specified in thestartTime parameter and the output is stored in the Content Store. The runAt() method is notcovered in this document.

12.2 The Asynchronous Conversation

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

Business Analytics

18

Page 19: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

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

An example of an application that makes extensive use of the asynchronous conversation is theCognos Viewer. Some of the more visible aspects of the asynchronous conversation are the rotatinghourglass that is used while waiting for output, the presentation of prompt pages, the submitting ofprompt values and paging up and down in an HTML report.

The details on the asynchronous conversation are contained in the IBM Cognos 8 SDK Developer’sGuide under the section titled Understanding the Asynchronous Conversation in the chapter RunningTasks. 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 whenlarge amounts of data are present in the report. As mentioned in the previous section, theprimaryWaitThreshold is used to determine the amount of time the run() method will wait for reportoutput. If this time expires and the report output is still not ready, then the IBM Cognos 8 SDKapplication 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 IBM Cognos 8 SDKapplication will remain in the wait() method until the report output is ready or the amount of timespecified by the run option secondaryWaitThreshold has passed. The default value for thesecondaryWaitThreshold is 30 seconds. An IBM Cognos 8 SDK application will generally just looparound the wait() method until the report output is ready.

The IBM Cognos 8 SDK Developer’s Guide states that it is possible to set either of the wait thresholdsto 0. This means that there will be no asynchronous conversation and the IBM Cognos 8 SDKapplication will wait until report data is returned or an error occurred. Waiting an indeterminate timeis generally considered to be a bad technique for production quality applications. This is a passiveapproach and is difficult, if not impossible, to react to errors. In addition, the application will usuallyrequire additional code to manage other time-sensitive resources such as communications sockets. Itis far better to learn about and use the asynchronous conversation to actively manage the processingof the report. Setting a wait threshold to zero or a high value is acceptable for learning purposes butis strongly discouraged for IBM Cognos 8 SDK applications operating in a production environment. Allwait 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 objectserves 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 theasynchronous conversation and will be updated by the wait() method.

Business Analytics

19

Page 20: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

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

The run options saveOutput, outputFormat and outputEncapsulation are the main drivers of wherereport output is stored and how the Cognos 8 SDK application will need to go about accessing thisoutput.

If the run 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 thereport object that was run.

● This reportVersion object will contain one or more child output objects. One output objectwill be created for each output format specified in the outputFormat run option.

● The list of output objects is obtained with the getOutputObjects() method ofasynchDetailReportOutput.

Note that the runSpecification() method cannot have saved output since there is no correspondingreport object in the Content Store that can contain the reportVersion object created to hold the savedoutput.

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 optionoutputEncapsulation.

● OutputEncapsulationEnum.none

● The output will be returned in the asynchDetailReportOutput object and can beaccessed with the getOutputPages() method.

● OutputEncapsulationEnum.URL

● The getOutputPages() method of the asynchDetailReportOutput object will contain aURL that points to the report output.

● In addition, the getOutputObjects() method of the asynchDetailReportOutput objectwill contain a complete search path to a temporary Content Store object that holdsthe report output.

● OutputEncapsulationEnum.URLQueryString

● The getOutputPages() method of the asynchDetailReportOutput object will contain

Business Analytics

20

Page 21: Approach to the IBM Cognos 8 SDK

Approach To The IBM Cognos 8 SDK

only the query string of a URL. The query string of a URL is everything that followsthe “?” that is often seen after the URL’s path component.

● In addition, the getOutputObjects() method of the asynchDetailReportOutputobject will contain a complete search path to a temporary Content Store object thatholds the report output.

● OutputEncapsulationEnum.HTML

● The HTML output can be accessed with the getOutputPages() methodasynchDetailReportOutput object. If the output format was HTML, then the actualreport output will be returned. If the output format was not HTML, then an HTMLpage that references the report output will be returned.

As can be seen from this list, specifying any of the outputEncapsulation values except “none” willcause the report output to be stored in a temporary Content Store object. If the report being run islarge, not having the report output stored could cause the IBM Cognos 8 SDK application to run outof memory as it attempts to retrieve the report output all at once. If the report output is placed in theContent Store, it is possible to query the Content Store object and retrieve the output in smallerchunks.

13 For More Information

There are many Technotes that contain sample code that demonstrate how to perform a wide arrayof tasks using the IBM Cognos 8 SDK.

To access these Technotes , go to the main IBM Cognos Support Portal at,

http://www-947.ibm.com/support/entry/portal/Overview/Software/Information_Management/Cognos_Business_Intelligence_and_Financial_Performance_Management

and type “SDK sample” in the Search support field on the left hand side of the page.

14 ConclusionThe information in this document should provide a basic foundation for the IBM Cognos 8 SDK. Usingthis foundation, there should be little problem in navigating the entire IBM Cognos 8 SDKdocumentation set and making use of other IBM Cognos 8 services to build robust applications.

Business Analytics

21