IBM Cognos Proven Practices: Approach to the IBM Cognos 8 SDK

Nature of Document: Tip or Technique; Product(s): IBM Cognos 8; Area of Interest: Development

The IBM 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 IBM Cognos 8 Connection can be re-created using the IBM Cognos 8 SDK.

Share:

Introduction

Overview

Develop skills on this topic

This content is part of a progressive knowledge path for advancing your skills. See Introduction to IBM Cognos Business Intelligence V10.01

The IBM 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 IBM Cognos 8 SDK.

As of version 8.4.1, the IBM Cognos 8 SDK documentation contains over 2900 pages in PDF form. In addition to the documentation, there are code samples that are installed with the SDK and a considerable number of Technotes and SupportLink articles related to the IBM Cognos 8 SDK. For someone just starting out with the IBM 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 IBM Cognos 8 SDK application. Once comfortable with these knowledge elements, it will be much easier to navigate and pinpoint information in the IBM 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 IBM 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 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 about what 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
  • 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 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 IBM 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 IBM Cognos 8 or from formal training courses offered by IBM Cognos Education. More information on the IBM Cognos Education training offerings can be found at http://www.ibm.com/software/data/education/cognos.html.

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.

Scope of Document

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


Get The Right Tools For The Job

Before beginning, it is strongly recommended that an Integrated Development Environment (IDE) 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 IBM Cognos 8 SDK applications in Java, the Eclipse IDE is widely used and can be 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 used as the IDE. There are also no-cost open source IDEs available.

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

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


About IBM Cognos 8 Web Services

IBM Cognos 8 is built using an architecture based on Web Services and the IBM 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 IBM 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.


Deploy a Standalone IBM Cognos 8 Installation

When starting out with the IBM 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 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 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, an IBM 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 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 group in the Cognos namespace the permissions of the built-in System Administrators role. The IBM 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 IBM Cognos 8 SDK application will need to use this user account to authenticate and logon to IBM Cognos 8.


Sample Deployments And Data

It is strongly recommended that some of the IBM Cognos 8 BI sample deployments and data be installed before using the IBM Cognos 8 SDK. This will create a standalone reporting environment and provide 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 should assistance be required

It is also recommended that some of the sample reports be executed through IBM 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 IBM Cognos Connection is available through the IBM Cognos 8 SDK.


Content Store Layout and Search Paths

The objects that the IBM 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 IBM Cognos 8 SDK Developer’s Guide.

  • For IBM Cognos 8 BI versions 8.1, 8.2 and 8.3 see the section Content Store Structure within 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 in developing IBM 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 IBM Cognos 8 SDK Developer’s Guide provides detailed information on search paths, including how to obtain a search path to an individual object using IBM 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 IBM Cognos 8 SDK application is using for authentication. More information on logging 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 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. 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 IBM 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 the IBM Cognos 8 SDK Developer's Guide, the chapter Classes contains a section titled Content Manager Containment Relationships. This section is very useful as a quick reference guide to determine where in the Content Store hierarchy an object resides and what the search path to the object will be.

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

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 Content Store.

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 an IBM 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.


Enumeration Sets

In the context of the IBM 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 many enumeration sets in the IBM Cognos 8 SDK (80+ in version 8.2 and 110+ in version 8.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
    • asynchReplyStatusEnum
    • asynchDetailReportStatusEnum

The complete list of enumeration sets can be found in the IBM 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.


All Those Classes

There are several hundred classes that make up the IBM Cognos 8 SDK. Each class is listed and described 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

Classes that represent Content Store objects

The classes that represent Content Store objects are the ones that an IBM 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 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 listed below.
  • uiClass – defines properties that can be manipulated through IBM 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.

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 are classes that implement properties of Content Store objects. In fact, all IBM Cognos 8 SDK properties are 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 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. In version 8.2 there are over 300 classes that represent properties, in version 8.4 there are over 400.


The IBM Cognos 8 Services

The IBM Cognos 8 services are an SDK application’s interface to the IBM Cognos 8 server. Depending on 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, 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.

Internally, an IBM Cognos 8 service may call another IBM 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 IBM 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 IBM 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.

For detailed information on each of the IBM Cognos 8 services, the methods available to each service and code samples on how to create and connect to an IBM Cognos 8 service, see the chapter titled Services 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 named CognosReportNetService. This service is provided for compatibility purposes for SDK applications that were written for IBM Cognos ReportNet. The CognosReportNetService was listed as deprecated with the release of version 8.1 and was removed from the product with version 8.3.


Logging On and Logging Off

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

Unless Anonymous access is allowed, when an IBM Cognos 8 SDK application is connected to the IBM Cognos 8 server the application has no implied rights or access permissions. The IBM Cognos 8 SDK application needs to login just as an interactive user would login. If anonymous access is allowed, the IBM 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 an IBM Cognos 8 SDK application does not login, an exception will occur when the 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 by the logon() and logoff() methods. None of the other IBM Cognos 8 services can perform a logon or logoff operation.

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

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 IBM Cognos 8 SDK application in the BIBusHeader. When an IBM Cognos 8 SDK application creates an object to represent an IBM Cognos 8 service, that object will contain a property called BIBusHeader. The BIBusHeader represents the SOAP header that is used to communicate with the IBM 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 IBM Cognos 8 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 IBM Cognos 8 SDK contain code that demonstrate how to connect to an IBM Cognos 8 service, how to logon using the ContentManagerService and how to copy a BIBusHeader from the ContentManagerService to another service.

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 connectToCognosServer methods. This is a utility method that will connect many of the IBM Cognos 8 services to the same URL.

Once the IBM Cognos 8 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 an IBM Cognos 8 service name. The process of copying the BIBusHeader from the ContentManagerService to another IBM Cognos 8 service is the same, regardless of the service.

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 to set the Url property of IBM 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.

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 8 server. This means any other authenticated IBM 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 IBM Cognos 8 SDK application does not explicitly log off, the session will remain active until it is timed out. All SDK applications that have logged in should log off when processing is done.


Query the Content Store

At some point, a typical IBM 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.

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 IBM Cognos 8 SDK application will involve processing the properties of the retrieved Content Store object(s).

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.

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>
}

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.

When discussing IBM 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 IBM Cognos 8 to generate a report. The XML document has no meaning outside of IBM 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 IBM 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 IBM Cognos 8 SDK application. However, in terms of the IBM 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 the IBM Cognos 8 SDK Developer’s Guide contains information related to running reports.

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 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 IBM 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).

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 IBM 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 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 the startTime parameter and the output is stored in the Content Store. The runAt() method is not covered in this document.

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 an IBM Cognos 8 SDK application to run a report in such a complex environment, the asynchronous conversation is used.

When first starting out with the IBM 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 IBM 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 IBM 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 IBM 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 IBM 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. An IBM Cognos 8 SDK application will generally just loop around 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 thresholds to 0. This means that there will be no asynchronous conversation and the IBM 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 IBM Cognos 8 SDK applications operating in a production environment. All wait thresholds are specified in seconds.

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 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 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.
  • 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.
    • OutputEncapsulationEnum.none
      • The output will be returned in the asynchDetailReportOutput object and can be accessed with the getOutputPages() method.
    • 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.
    • 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.
    • 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.

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


For More Information

There are many Technotes that contain sample code that demonstrate how to perform a wide array of 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.


Conclusion

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

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Big data and analytics on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Big data and analytics, Information Management
ArticleID=489913
ArticleTitle=IBM Cognos Proven Practices: Approach to the IBM Cognos 8 SDK
publish-date=05182010