Hand Sons Dk

Hands-on IBM Cognos Software Development Kit Programming

Nature of Document: Proven Practice

Product(s): IBM Cognos Software Development Kit

Area of Interest: Development

Business Analytics


Copyright and Trademarks Licensed Materials - Property of IBM.

© Copyright IBM Corp. 2011

IBM, the IBM logo, and Cognos are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks 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 is accurate and complete, some typographical errors or technical inaccuracies may exist. IBM does not accept responsibility for any kind of loss resulting from the use of information contained in this document. The information contained in this document is subject to change without notice.

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

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.

Business Analytics IBM Confidential

2

http://www.ibm.com/legal/copytrade.shtml

mailto:[email protected]


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

1.1 Purpose..............................................................................................................................41.2 Applicability........................................................................................................................4

2 What is the IBM Cognos Software Development Kit?........................................................4

2.1 Uses for the IBM Cognos Software Development Kit..............................................................42.2 The API of the IBM Cognos Software Development Kit..........................................................52.3 The IBM Cognos Software Development Kit documentation...................................................52.4 How to install IBM Cognos Software Development Kit...........................................................52.5 How IBM Cognos Software Development Kit works...............................................................6

3 The Structure of an IBM Cognos Software Development Kit Program................................8

3.1 Step 1: Connect To The IBM Cognos BI Server.....................................................................83.2 Step 2: Logon To The IBM Cognos BI Server........................................................................93.3 Step 3: Execute tasks........................................................................................................103.4 Step 4: Logoff From The IBM Cognos BI Server..................................................................113.5 The Java code...................................................................................................................11

4 Search Paths...............................................................................................................14

4.1 Search path for one object.................................................................................................154.2 Search path for multiple objects.........................................................................................16

5 How to Run the IBM Cognos Software Development Kit Samples....................................17


3


1 Introduction

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

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


4


2 What is the IBM Cognos Software Development Kit?

2.1 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

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


5


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.

2.3 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

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

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


6


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


7


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.


8


3 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 BI3. 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.

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


9


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.

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


10


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.


11


3.3 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)']

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

3.5 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


12


• 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 servicesmainClass.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();

}


13


// Step 1: Connect to the Cognos servicesprivate 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();

}}


14


// 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();

}}


15


4 Search PathsA 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.

4.1 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


16


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

4.2 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


17


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


18

Documents

Hand Sons Dk