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

An introductory document to the IBM Cognos SDK that explains the basic requirements of an SDK application using a stand-alone sample.

Share:

Claudiu Popescu, Software Engineer, IBM Cognos SDK Support Group, IBM

Claudiu PopescuClaudiu 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.



20 May 2011

Also available in Spanish

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,

  • 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 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 workstation-based 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.

Illustration 1: IBM Cognos 10 Services listed in the IBM Cognos Configuration
Illustration 1: IBM Cognos 10 Services listed in the IBM Cognos Configuration
Illustration 2: IBM Cognos 10 Services listed in IBM Cognos Administration
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:

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

Illustration 3: IBM Cognos Configuration showing the “Dispatcher URI for external applications” field
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.

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

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,

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 java.net.URL;
import javax.xml.namespace.QName;
import org.apache.axis.client.Stub;
import org.apache.axis.message.SOAPHeaderElement;
import com.cognos.developer.schemas.bibus._3.BaseClass;
import com.cognos.developer.schemas.bibus._3.BiBusHeader;
import com.cognos.developer.schemas.bibus._3.ContentManagerService_PortType;
import com.cognos.developer.schemas.bibus._3.ContentManagerService_ServiceLocator;
import com.cognos.developer.schemas.bibus._3.PropEnum;
import com.cognos.developer.schemas.bibus._3.QueryOptions;
import com.cognos.developer.schemas.bibus._3.SearchPathMultipleObject;
import com.cognos.developer.schemas.bibus._3.Sort;
import 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

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

	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.

Illustration 5: The "Set Properties" icon in IBM Cognos Connection
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
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 :

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


Download

DescriptionNameSize
Article contained in ZIP fileHandsOnSDK.zip579KB

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=659920
ArticleTitle=IBM Cognos Proven Practices: Hands-on IBM Cognos Software Development Kit Programming
publish-date=05202011