Cognos SDK Guide by BI Centre Version 1.

Table of Contents
-----------------------------------------------------------------------------------------------

i. Version and Disclaimer

ii. Overview
iii. Getting started with your ASP.NET C# web solution
1. VS.NET Version
2. Cognos SDK DLL references
3. Project Structure
iv. Creating your SDK object class
1. Authentication
2. Get Content Store Objects
3. Get Params
4. Helper Functions
v. Exception Handler Class
vi. Web.config
1. Storing credential values
vii. Searching for Content Store Items
1. Show all packages
2. Show reports for a package
3. Run a report with prompts
4. Displaying the report results
viii. Step-by-step
1. Default.aspx
2. Reports.aspx
3. PromptPage.aspx
4. Output.aspx
ix. Contact for more information

Version_______________________________________________

Version 1.0: December 23rd, 2007

This document applies to the “Cognos_SDK_template” C# web solution and a sample Cognos 8.1 report
based on the GOSR package.

The specific software versions used were:

Microsoft .NET Framework 1.1 Version: 1.1.4322 SP1
Visual Studio .NET 2003 Version: 7.1.3088
Cognos 8.1
• C8BISRVR_version=C8BISRVR-AW-ML-RTM-8.1.108.33-0
• C8BIMODEL_version=C8BIMODEL-AW-ML-RTM-8.1.108.33-0
• C8SDK_version=C8SDK-AW-ML-RTM-8.1.60.28-0

Disclaimer_______________________________________________

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.
BI Centre does not accept responsibility for any kind of loss resulting from the use of
information contained in this document.

This document shows the creation date, and the information contained within this
document is subject to change without notice.

No part of this document, or the included sample project, may be copied, photocopied,
reproduced, transmitted in any form or by any means, or translated into another
language without the prior written consent of the BI Centre.
Overview_______________________________________________

The Cognos SDK Guide by BI Centre is intended to provide a Cognos SDK developer with a workable C#
solution that will allow you to:

• Search the Content Store for all package items

• Search the Content Store for all reports that belong to a specified package
• Generate a report’s prompt page
• Execute the report
• Display the report results in a browser window
• Handle SOAP exceptions and render a meaningful error message to the user

The Cognos SDK Guide by BI Centre will walk you through the steps of generating your ASP.NET C#
web solution and guide you through the process of creating your: ASP.NET pages; C# Class Files for
Exception handling and Cognos SDK method calls; supporting JavaScript code; deciding upon which
Cognos SDK DLLs to reference; and handling basic security by using the web.config.

Getting started with your ASP.NET C# solution_______________

We will be developing our sample web solution with Visual Studio .NET 2003 (VS.NET 2003). VS.NET
2003 uses .NET Framework 1.1 and that means that we need to use both cognosdotnet.dll and
cognosdotnetassembly.dll in our web solution. If we were using .NET Framework 2.0 then we could use
cognosdotnet_2_0.dll and cognosdotnetassembly_2_0.dll.

The full source code has been provided for you and this step would be to cover the steps in order to
generate the solution’s project structure.

Let’s get started by building the sample file and folder structure for your solution:

1. Create a new C# web application in VS.NET 2003 and name it “Cognos_SDK_template”.

2. Expand the project and right-click on References. Go ahead and add both the cognosdotnet.dll
and cognosdotnetassembly.dll to your solution.
3. You will also have to ensure that System.Web.Services has been added to your solution.
4. Select the project name “Cognos_SDK_template” and right-click.
1. Add a folder and name it “includes”.
2. Add a C# Class file and name it “CognosSDK.cs”.
3. Add a C# Class file and name it “ExHandler.cs”.
4. Add a new .ASPX page and name it “Default.aspx”.
i. Right-click on this file and select “Set as Start Page”.
5. Add a new .ASPX page and name it “Reports.aspx”.
6. Add a new .ASPX page and name it “PromptPage.aspx”.
7. Add a new .ASPX page and name it “RunReport.aspx”.
8. Add a new .ASPX page and name it “Output.aspx”.
9. Add a new .HTML page and name it “PleaseWait.htm”.
5. Select the “includes” folder and right-click.
1. Add a new .js file and name it “CognosSDKHelper.js”.
2. You can do an internet search for a clipart that represents an hour glass and save the
file in the “includes” folder as “executing.gif”.

You have now successfully created the main skeletal structure for your ASP.NET C#
solution.

Creating your SDK object -- CognosSDK.cs__________________

The CognosSDK.cs class file is used primarily for interacting with your Cognos Content Store. You will
be adding methods that will enable you to: Authenticate and connect to the Cognos service; request and
return Cognos Content Store objects; request and set report parameter values; and execute a report.

Authentication
The CognosLogon() method handles the authentication to the Cognos Report Service. This method
permits a BIBus API value to be set and connected to Cognos 8. We have stored our authentication
values in our web solution’s web.config file. We’ll discuss how to retrieve these values in the section
named – web.config.

Here is the example code to authenticate a user to Cognos 8. The code is appending encoded xml with
the stored values from the web.config file. The Content Manager service’s .logon() method is passed the
encoded xml and it will return a valid CAMPassportId. If the user fails to be authenticated then an error
message is passed to a string variable, which can then be displayed to the end user.

public string CognosLogon(contentManagerService1 cmService, string

NmSpace,string uid, string pwd)
{
string CAMPassportID;
string credentialXML;
credentialXML= "<credential><namespace>"+ NmSpace + "</namespace>";
credentialXML= credentialXML +"<username>" + uid + "</username>";
credentialXML= credentialXML +"<password>" + pwd +
"</password></credential>";
try
{
xmlEncodedXML xmlPath = new xmlEncodedXML();
xmlPath.Value = credentialXML;
cmService.logon(xmlPath,new searchPathSingleObject[]{});
CAMPassportID = _cmService.biBusHeaderValue.CAM.CAMPassport.id.ToString();
return CAMPassportID;
}

catch (Exception ex)

{
return _ErrMsg = ex.Message.ToString();
}
}

Request Content Store Objects

The Cognos Content Store contains the metadata representation of items such as reports, query items,
report views, and security settings. The Cognos SDK code can call the Content Manager’s .query()
method to search for and retrieve Content Store items. The getObjects() method is an example of
searching the Content Store and finding either all Content Store package items or all report items for a
specified package.
public baseClass[] getObjects(contentManagerService1 _cmService, string
_path, string _package)
{
propEnum[] _props = new
propEnum[]{propEnum.searchPath,propEnum.defaultName,propEnum.objectClass,
propEnum.modificationTime, propEnum.connectionString, propEnum.creationTime,
propEnum.link, propEnum.specification, propEnum.version,
propEnum.defaultName, propEnum.portalPages, propEnum.ancestors,
propEnum.owner};
if(_cmService != null)
{
sort[] _sort = {new sort()};
_sort[0].order=orderEnum.ascending;
_sort[0].propName=propEnum.defaultName;

_packagePath = "/content//package/*";
_reportPath = "/content/package[@name='" + _package + "']/report//*";

searchPathMultipleObject _spMulti = new searchPathMultipleObject();

if (_path == "packageConfiguration")
{
_path = _packagePath;
}
else if (_path == "report")
{
_path = _reportPath;
}
else
{
_path = null;
}
_spMulti.Value = _path;
try
{
//Query Cognos 8 and return the Base Class Array to the calling method
baseClass[] _bc = _cmService.query(_spMulti, _props, _sort, new
queryOptions());
if(_bc != null)
{
//if the search request returned results
if(_bc.Length > 0)
{
return _bc;
}
else
{
return null;
}
}
}
catch(Exception ex)
{
_ErrMsg = ex.Message.ToString();
return null;
}
}

//no results found

return(null);
}

Step-by-step_________________________________________________

Default.aspx

When the application is launched it loads all of the packages that exist within your Content Store into a
listbox control. You would select the desired package name from the list and then click the ‘Go To
Reports’ button.
Reports.aspx

After you selected your package you are then displayed a list of all of the report items
that exist within your specified package. In this case, we see two reports that are based
on the GOSR package. Remember, that the GOSR package is a demonstration
package provided by Cognos.

You would select the requested report from the listbox control and then click the ‘Execute Report’ button.
We have provided the Product Line report xml specification within the “Product Line report spec.txt” file
that is provided with your .NET solution.
PromptPage.aspx

The application renders your report’s prompt page and displays the user prompts to the
user. When the prompt control is highlighted red it means that a value must be selected
in order to satisfy your report’s prompt requirements.

In this scenario you must enter a value from the drop down list to provide a parameter value for the
product line prompt. Once you selected a value then you will click the ‘Finish’ button. If the ‘Finish’ button
is disabled, or grayed out, then you must confirm that you have successfully selected a prompt value from
the drop down list.
Output.aspx

After you have satisfied your report’s request for selecting a prompt value and click the ‘Finish’ button,
you are then displayed a message stating that the report is currently being executed.

Once the Cognos Report Service has been able to execute the report the results are
then displayed.
Contact for more information______________________________

If you have any questions or require assistance then be sure to check out BI Centre SDK Guide and BI
Centre for updates related to this code.

You can also email us your questions.

1/13