IBM Cognos Proven Practices: Hands-on IBM Cognos

Software Development Kit Programming

Nature of Document: Proven Practice; Product(s): IBM Cognos
Software Development Kit; Area of Interest: Development
Claudiu Popescu
Software Engineer, IBM Cognos SDK Support Group
IBM

20 May 2011

An introductory document to the IBM Cognos SDK that explains the basic requirements of an
SDK application using a stand-alone sample.
View more content in this series

Introduction
Purpose
This document is addressed to the software designers who are very familiar with the IBM Cognos
BI product and who would like to use the IBM Cognos BI Software Development Kit (SDK)
component. The IBM Cognos Software Development Kit contains many samples but they may
be intimidating for someone just starting out with the SDK because they are somewhat complex
and are not stand-alone as they make use of classes that are defined in other directories. This
document offers a simpler approach in that it contains only one source file with a self-contained
SDK application.

Applicability
This document has been written using IBM Cognos BI version 10.1 as the reference version.
However, the concepts presented also apply to versions 8.3 and greater of IBM Cognos 8 BI. The
code sample supplied with this document will need to be adapted to work with IBM Cognos 8 BI.

What is the IBM Cognos Software Development Kit?

Uses for the IBM Cognos Software Development Kit
The IBM Cognos Software Development Kit is an additional install component which allows the
programmatic execution of,
Copyright IBM Corporation 2011
IBM Cognos Proven Practices: Hands-on IBM Cognos Software
Development Kit Programming

Trademarks
Page 1 of 14

developerWorks

ibm.com/developerWorks/

Most of the tasks that can be performed through the IBM Cognos BI user interface (UI)
The automation of repetitive non-UI tasks, such as scheduling large number of reports,
changing permissions for many reports, etc
Integrating IBM Cognos BI into other applications.
Examples of IBM Cognos Software Development Kit specific tasks include,

Display all IBM Cognos BI users and their access to reports

Assign a new owner to all reports for which the original owner was deleted
After a package is republished, update the reports and queries belonging to the package.
Display a list of IBM Cognos BI reports in a custom web page

However, the IBM Cognos Software Development Kit cannot be used for tasks that are typically
associated with configuration and packaged user interfaces. For example, the SDK cannot modify
IBM Cognos BI user interface components such as,

Portal Pages
Logon Pages
Any user interface widgets
Studios in IBM Cognos Connection
Branding

The API of the IBM Cognos Software Development Kit

The main component of IBM Cognos Software Development Kit is the Application Programming
Interface (API) known as the BI Bus API. IBM Cognos Software Development Kit API supports
specific programming languages through the use of toolkits. The supported programming
languages are,
Java
.NET Framework languages
IBM Cognos Software Development Kit API can be used either in stand-alone programs or in web
pages, such as ASPs or JSPs.
In addition to the toolkits, there are other IBM Cognos Software Development Kit components
which will not be presented in this document. The other components are,
URL interface which is used to automate actions by passing commands and parameters over
HTTP in order to integrate with other applications
Framework Manager (FM) SDK which is used to model metadata and publish packages
Cognos Mashup Services (CMS) which exposes a REST and WSDL/SOAP interface to IBM
Cognos BI outputs so that this output can be easily consumed by other applications.

The IBM Cognos Software Development Kit documentation

The IBM Cognos Software Development Kit documentation is divided into the following
components (the number of pages are from the IBM Cognos 10 document set),
IBM Cognos Proven Practices: Hands-on IBM Cognos Software
Development Kit Programming

Page 2 of 14

ibm.com/developerWorks/

developerWorks

IBM Cognos Software Development Kit Getting Started (44 pages)

IBM Cognos Software Development Kit Installation and configuration guide (15 pages)
IBM Cognos Software Development Kit Developer Guide (3565 pages)
IBM Cognos Custom Authentication Provider Developer Guide (41 pages)
IBM Cognos Framework Manager Developer Guide (172 pages)
IBM Cognos Mashup Service Developer Guide (275 pages)

Since the IBM Cognos Software Development Kit documentation is quite large, the new user is
encouraged to read about the essentials of the SDK in the developerWorks article IBM Cognos
Proven Practices: Approach to the IBM Cognos SDK, which can be found at the following URL,
http://www.ibm.com/developerworks/data/library/cognos/development/how_to/page129.html

How to install IBM Cognos Software Development Kit

The IBM Cognos Software Development Kit must be installed on a computer where any server
component of IBM Cognos BI is already installed. The SDK installation procedure is similar to the
IBM Cognos BI Server installation procedure.
The remainder of this document assumes that the IBM Cognos Software Development Kit has
been installed and an IBM Cognos BI Server is available. It is recommended, if possible, that a
single server install be used when just starting out with the SDK. A Windows or Linux workstationbased install of IBM Cognos BI that uses the IBM Cognos Content Store and the deployment of
the sample IBM Cognos PowerCubes makes an excellent self contained learning environment.

How IBM Cognos Software Development Kit works

The IBM Cognos Software Development Kit API contains classes which correspond to IBM
Cognos BI services such as the Content Manager Service, the Report Service or the Monitor
Service. The services that are available on an IBM Cognos BI server are specified in IBM Cognos
Configuration and can be seen in under the Configuration tab in IBM Cognos Administration.

IBM Cognos Proven Practices: Hands-on IBM Cognos Software

Development Kit Programming

Page 3 of 14

developerWorks

ibm.com/developerWorks/

Illustration 1: IBM Cognos 10 Services listed in the IBM Cognos Configuration

Illustration 2: IBM Cognos 10 Services listed in IBM Cognos Administration

An IBM Cognos Software Development Kit program can run on a computer which does not have
the IBM Cognos BI server installed. However the IBM Cognos Software Development Kit libraries
are required to be installed on this computer. The SDK libraries are located at:
IBM Cognos Proven Practices: Hands-on IBM Cognos Software
Development Kit Programming

Page 4 of 14

ibm.com/developerWorks/

developerWorks

<cognos-directory>\sdk\java\lib for Java; axisCognosClient.jar is the main Java SDK library

and the rest of the jar files are to support axisCognosClient.jar and the samples that are
installed with the SDK
<cognos-directory>\sdk\csharp\lib for the .NET languages
An IBM Cognos Software Development Kit application will generally supply a set of credentials to
the IBM Cognos BI server and the application will be bound and limited to these credentials. This
means that the SDK application must be authenticated to perform operations in the same way a
user needs to logon to the IBM Cognos Connection. This ensures secure access to IBM Cognos
content.

The Structure of an IBM Cognos Software Development Kit Program

A typical IBM Cognos Software Development Kit program has four primary sections.
1. Connect to the IBM Cognos BI service(s)
2. Logon to IBM Cognos BI
3. Execute tasks
4. Logoff from IBM Cognos BI
This document contains a sample SDK application written in Java and contains methods that
correspond to these primary sections.

Step 1: Connect to the IBM Cognos BI server

Method name : connectToCognos
The IBM Cognos Software Development Kit program must first connect to an IBM Cognos BI
Dispatcher using the URL of the IBM Cognos BI server. This URL is defined in IBM Cognos
Configuration and is the value of the Dispatcher URI for external applications field. The URL has
the form http://host.domain:port/p2pd/servlet/dispatch.

IBM Cognos Proven Practices: Hands-on IBM Cognos Software

Development Kit Programming

Page 5 of 14

developerWorks

ibm.com/developerWorks/

Illustration 3: IBM Cognos Configuration showing the Dispatcher URI for

external applications field

Once connected to an IBM Cognos BI Dispatcher, the IBM Cognos Software Development
Kit application requests an IBM Cognos BI service. Unless the application is going to use the
Anonymous credentials, the application must request the Content Manager service because that is
the service that handles the logon/logoff processes.

Step 2: Logon to the IBM Cognos BI server

Method name : logonToCognos
Logon is done through the Content Manager service. IBM Cognos BI supports both authenticated
and anonymous user access. In this step, if the anonymous access is disabled, then the SDK
application must logon using a namespace ID, a user name and its associated password. The
namespace ID is the value of the Namespace ID field in IBM Cognos Configuration.

IBM Cognos Proven Practices: Hands-on IBM Cognos Software

Development Kit Programming

Page 6 of 14

ibm.com/developerWorks/

developerWorks

Illustration 4: The "Namespace ID" field in IBM Cognos Configuration

The namespace ID, user name and password are supplied in an XML string known as a credential.
The credential takes the form of,
<credential>
<namespace>namespaceID</namespace>
<username>user<username>
<password>pwd</password>
</credential>

In the sample Java code, note the 3 lines following the call to the logon() method. These lines are
required to retrieve and store information related to the authenticated session into the cmService
variable. In IBM Cognos 8 this was handled automatically but in IBM Cognos 10, this must be done
programmatically as some of the session related information is dynamic and needs to be refreshed
before calling an IBM Cognos 10 service. For more information on this, see the Managing Service
Headers topic in the chapter titled Coding Practices and Troubleshooting in the IBM Cognos 10
SDK Developers guide.

Step 3: Execute application specific tasks

Method name : executeTasks
This step performs the specific tasks of the application. The code example shows how to display
the list of packages in the Public Folders. The Content Manager Service performs a query
with the "/content//package" search path and extracts the searchPath and the defaultName
properties. The search path syntax is described in Section 4 below. The query returns an array of
BaseClass objects, which is then printed. If the IBM Cognos BI samples have been installed, the
output will look similar to,

IBM Cognos Proven Practices: Hands-on IBM Cognos Software

Development Kit Programming

Page 7 of 14

developerWorks

ibm.com/developerWorks/

GO Data Warehouse (analysis) - /content/folder[@name='Samples']/folder[@name='Models']

/package[@name='GO Data Warehouse (analysis)']
GO Data Warehouse (query) - /content/folder[@name='Samples']/folder[@name='Models']
/package[@name='GO Data Warehouse (query)']
GO Sales (analysis) - /content/folder[@name='Samples']/folder[@name='Models']
/package[@name='GO Sales (analysis)']
GO Sales (query) - /content/folder[@name='Samples']/folder[@name='Models']
/package[@name='GO Sales (query)']
Sales and Marketing (conformed) - /content/folder[@name='Samples']/folder[@name='Models']
/package[@name='Sales and Marketing (conformed)']

Step 4: Logoff from the IBM Cognos BI server

Method name : logoffFromCognos
The logoff is done through the Content Manager service. If an SDK application terminates without
logging off, the resources that were allocated for the IBM Cognos 10 session that was established
when the SDK application logged on will remain allocated until the session times out.

The Java code example

The following code is contained in the ZIP file attachment that accompanies this document. Unzip
to the <c10_install>/sdk/java directory and a folder called SDKExample will be created. From the
SDKExample folder, you can use the build.bat/build.sh scripts to build the application and you can
use the run.bat/run.sh scripts to run the application.
Before building and running this example, there needs to be some editing of the Java source file,
the build script and the run script.
In the file SDKExample.java the variables nameSpaceID, userName and password must be
modified to contain values that will work in your environment
In the build and run scripts, the JAVA_HOME variable must be set to the path to the JDK
used, with the minimum JDK version being 1.5 (also known as JDK 5.0). In the build.sh and
run.sh scripts it may also be necessary to set the CRN_HOME environment variable.
import
import
import
import
import
import
import
import
import
import
import
import
import

java.net.URL;
javax.xml.namespace.QName;
org.apache.axis.client.Stub;
org.apache.axis.message.SOAPHeaderElement;
com.cognos.developer.schemas.bibus._3.BaseClass;
com.cognos.developer.schemas.bibus._3.BiBusHeader;
com.cognos.developer.schemas.bibus._3.ContentManagerService_PortType;
com.cognos.developer.schemas.bibus._3.ContentManagerService_ServiceLocator;
com.cognos.developer.schemas.bibus._3.PropEnum;
com.cognos.developer.schemas.bibus._3.QueryOptions;
com.cognos.developer.schemas.bibus._3.SearchPathMultipleObject;
com.cognos.developer.schemas.bibus._3.Sort;
com.cognos.developer.schemas.bibus._3.XmlEncodedXML;

public class SDKExample {

private static String dispatcherURL = "http://localhost:9300/p2pd/servlet/dispatch";
private static String nameSpaceID = "NSID";
private static String userName = "user";
private static String password = "pwd";
private ContentManagerService_PortType cmService=null;
public static void main(String args[]) {
SDKExample mainClass = new SDKExample(); // instantiate the class

IBM Cognos Proven Practices: Hands-on IBM Cognos Software

Development Kit Programming

Page 8 of 14

ibm.com/developerWorks/

developerWorks

// Step 1: Connect to the Cognos services

mainClass.connectToCognos (dispatcherURL);
// Step 2: Logon to Cognos
mainClass.logonToCognos(nameSpaceID, userName, password);
// Step 3: Execute tasks
mainClass.executeTasks();
// Step 4: Logoff from Cognos
mainClass.logoffFromCognos();
}
// Step 1: Connect to the Cognos services
private void connectToCognos(String dispatcherURL) {
ContentManagerService_ServiceLocator cmServiceLocator =
new ContentManagerService_ServiceLocator();
try {
URL url = new URL(dispatcherURL);
cmService = cmServiceLocator.getcontentManagerService(url);
} catch (Exception e) {
e.printStackTrace();
}
}
// Step 2: Logon to Cognos
private void logonToCognos(String nsID, String user, String pswd) {
StringBuffer credentialXML = new StringBuffer();
credentialXML.append("<credential>");
credentialXML.append("<namespace>").append(nsID).append("</namespace>");
credentialXML.append("<username>").append(user).append("</username>");
credentialXML.append("<password>").append(pswd).append("</password>");
credentialXML.append("</credential>");
String encodedCredentials = credentialXML.toString();
XmlEncodedXML xmlCredentials = new XmlEncodedXML();
xmlCredentials.set_value(encodedCredentials);
try {
cmService.logon(xmlCredentials, null);
SOAPHeaderElement temp = ((Stub)cmService).getResponseHeader(
"http://developer.cognos.com/schemas/bibus/3/", "biBusHeader");
BiBusHeader CMbibus = (BiBusHeader)temp.getValueAsType(
new QName ("http://developer.cognos.com/schemas/bibus/3/",
"biBusHeader"));
((Stub)cmService).setHeader(
"http://developer.cognos.com/schemas/bibus/3/",
"biBusHeader", CMbibus);
} catch (Exception ex) {
ex.printStackTrace();
}
}
// Step 3: Execute tasks
private void executeTasks() {
PropEnum props[] = new PropEnum[] { PropEnum.searchPath, PropEnum.defaultName };
BaseClass bc[] = null;
String searchPath = "/content//package";
try {
SearchPathMultipleObject spMulti =
new SearchPathMultipleObject(searchPath);
bc = cmService.query(spMulti, props, new Sort[] {}, new QueryOptions());
} catch (Exception e) {
e.printStackTrace();
return;

IBM Cognos Proven Practices: Hands-on IBM Cognos Software

Development Kit Programming

Page 9 of 14

developerWorks

ibm.com/developerWorks/

}
System.out.println("PACKAGES:\n");
if (bc != null) {
for (int i = 0; i < bc.length; i++) {
System.out.println(bc[i].getDefaultName().getValue() + " - "
+ bc[i].getSearchPath().getValue());
}
}
}
// Step 4: Logoff from Cognos
private void logoffFromCognos() {
try {
cmService.logoff();
} catch (Exception ex) {
ex.printStackTrace();
}
}

Search Paths
A search path is used to specify the location of objects in the IBM Cognos BI Content Store
hierarchy. A search path can specify a path to a single Content Store object or it can make use of
expressions and wildcard characters to retrieve more that one Content Store object
The search path syntax is similar to a path in an operating system such as DOS or UNIX. More
specifically, it resembles XPath which is a query language for selecting nodes from an XML
document.
The syntax of a search path is described in detail in Appendix A of the IBM Cognos Software
Development Kit Developer Guide.

Search path for one object

Example: A path taken from the IBM Cognos Connection UI, which locates the specific 'Budget vs.
Actual report in the 'Report Studio Report Samples folder :
/content/folder[@name='Samples']/folder[@name='Models']
/package[@name='GO Data Warehouse (analysis)']
/folder[@name='Report Studio Report Samples']
/report[@name='Budget vs. Actual']

To get the search path for a report, click on the Set properties icon for the report in IBM Cognos
Connection. In the Set properties dialog, click on the View the search path, ID and URL link. A
dialog will pop up, which contains the Search Path as the first field.

IBM Cognos Proven Practices: Hands-on IBM Cognos Software

Development Kit Programming

Page 10 of 14

ibm.com/developerWorks/

developerWorks

Illustration 5: The "Set Properties" icon in IBM Cognos Connection

Illustration 6: The search path of an IBM Cognos BI Content Store object as

seen using IBM Cognos Connection to view the object's properties

Search path for multiple objects

The wildcard character (*) indicates all the objects under the specified root. For example, to search
all the objects in the 'Report Studio Report Samples folder, use the search path :
/content/folder[@name='Samples']/folder[@name='Models']
/package[@name='GO Data Warehouse (analysis)']
/folder[@name='Report Studio Report Samples']/*

When a path starts with two slashes (//), all objects in the content store that fulfill the specified
criteria are selected. For example,
//folder will return all Folder objects in the Content Store
//report will return all Report objects in the Content Store
When a path contains //, all descendants of the current object that fulfill the specified criteria are
selected. For example, to select and return all the reports in the 'Report Studio Report Samples
folder, use the search path :
IBM Cognos Proven Practices: Hands-on IBM Cognos Software
Development Kit Programming

Page 11 of 14

developerWorks

ibm.com/developerWorks/

/content/folder[@name='Samples']/folder[@name='Models']
/package[@name='GO Data Warehouse (analysis)']
/folder[@name='Report Studio Report Samples']//report

How to Run the IBM Cognos Software Development Kit Samples

The IBM Cognos Software Development Kit has two different toolkits: Java and .NET. The toolkits
are located in the directory <cognos-directory>/sdk under the following folder names :
java for the Java toolkit
csharp for the .NET toolkit
Each of the toolkit directories contains many subdirectories with samples. The functionality of
each sample is described in the .html file under the same directory. Comments in the source
files describe the main purpose of each sample including a summary of which SDK methods are
used. The steps to use the samples in the toolkits are described in the IBM Cognos Software
Development Kit Getting Started guide.
To run a Java sample you have to build the Java sample first and then run it.

The script files for Windows are build.bat and run.bat

The script files for UNIX are build.sh and run.sh
A JDK must be installed on the computer
In each script file, the values of the two variables JAVA_HOME and CRN_HOME should be
updated with the actual values for the computer
It is also possible to build all the samples at once using build-samples.bat or build-samples.sh
scripts located at <cognos-directory>\sdk\java
To run the SDK samples with .NET, you must have version 2.0 or 3.0 of the .NET Framework
installed. To modify or rebuild the C# .NET samples, you must have a C# development
environment installed, such as Visual Studio 2005 or the .NET Framework Software Development
Kit (SDK) v2.0. In each sample, the build.bat script included with the sample code shows one way
of building the application using the Visual Studio .NET compiler.

IBM Cognos Proven Practices: Hands-on IBM Cognos Software

Development Kit Programming

Page 12 of 14

ibm.com/developerWorks/

developerWorks

Downloads
Description

Name

Size

Article contained in ZIP file

HandsOnSDK.zip

579KB

IBM Cognos Proven Practices: Hands-on IBM Cognos Software

Development Kit Programming

Page 13 of 14

developerWorks

ibm.com/developerWorks/

About the author

Claudiu Popescu
Claudiu Popescu is a member of the IBM Cognos SDK and Diagnostic Team. He
specializes in the Cognos Software Development Kit, Cognos Mashup Services and
JavaScript.

Copyright IBM Corporation 2011

(www.ibm.com/legal/copytrade.shtml)
Trademarks
(www.ibm.com/developerworks/ibm/trademarks/)

IBM Cognos Proven Practices: Hands-on IBM Cognos Software

Development Kit Programming

Page 14 of 14