Run a report with prompts -- CognosSDK.cs

Our working sample includes Report Studio reports that all contain prompts. In order for the reports to be executed they need to have their prompt page parameter objects populated with a valid parameter value. In order to achieve this we need to display the report's prompt page to the end user so that they can enter the prompt value into the appropriate prompt control. The approach that we will use to render the report's prompt page to the end user is to execute the selected report and satisfy the method's signature with an empty parameter value collection. Passing in an empty parameter value collection forces the Report Service to place the request into a 'prompting' status. We can then retrieve the request's HTML representation of the report's prompt page, and then render this HTML string to the ASP.NET page.



Note that our executeReport() method is looking for a Boolean value to state whether or not to prompt. When we want the prompt page then we set this Boolean value to True.



public string executeReport(string reportSearchPath,parameterValue[] pv, reportService1 reportService, string[] strFormat, bool blnPrompt){



………… method body………

…………

…………

}





The executeReport() method contains an asynchReply variable that is used to capture the conversation context of the request.



asynchReply C8reply = reportService.run(spSingle, pv ,arrRunOpts);





We will then pass the C8reply variable as an input parameter to the getOutputPage() method. This method will be used to populate a string variable with a string representation of the prompt page's HTML. It is this value that is written to PromptPage.aspx and displays the report's prompt page to the end user.



strHTML = getOutputPage(C8reply);





public string getOutputPage(asynchReply response)

{

asynchDetailReportOutput reportOutput = null;



try

{

for (int i = 0; i < response.details.Length; i++)

{

if (response.details[i] is asynchDetailReportOutput)

{

reportOutput =

(asynchDetailReportOutput)response.details[i];

break;

}

}

}

catch (SoapException exSoap)

{

ExHandler exCognos = new ExHandler(exSoap);

return _ErrMsg = exCognos.Details + " :-: " + exCognos.Message + " :-: " + exCognos.Severity + " :-: " + exCognos.ErrorCode;

}



//text based output is split into pages -- return the current page

return reportOutput.outputPages[0].ToString();

}



Before we display the prompt page to the end user we want make some modifications to the HTML that was returned. Our CustomizeHTML() helper function is used to update the HTML in order to work with our sample web solution. The main change will involve adding our own customized finish button to the prompt page to control the form's submission to Output.aspx. This will also enable us to add our own JavaScript function to the button's onClick() event. This is achieved in the CognosSDKHelper.js file.

Show reports for a package in Reports.aspx -- CognosSDK.cs

When you query the Cognos Content Store it is important to remember that you can search for one specific item, or you can search for all objects of a specified type. For example, if you wanted to find the details for one particular report item then you would use the following syntax for your search path value.



spSingle.Value = "/content/package[@name='" + _pkgName + "']/report[@name='" + _rptName + "']";





However, if you wanted to find all reports for a specified package then you would use the following syntax for your search path value.



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





This is the same logic if you wanted to find all packages that exist in the Cognos Content Store.



_packagePath = "/content//package/*";

Show All Packages in Default.aspx -- CognosSDK.cs

Show all packages

 

The entry point to our Cognos SDK web solution will be Default.aspx.  This will be a basic web page that will only contain a listbox control and a command button.  The listbox will be populated with all of the package items that exist in the specified Cognos Content Store.

 

Default.aspx will call the CognosSDK.cs object in order to query the Cognos Content Store for a list of Content Store objects.  In this case, we will only be interested in retrieving the list of all Content Store package objects that are of the type packageConfiguration.

 

The Default.aspx.cs PageLoad() event will contain the following C# code.

 

if (!Page.IsPostBack)

                  {

                       

                        baseClass[] _bc =  _cogSDK.getObjects(_cmService, _CSTypePkg, null);

                 

                        if (_bc != null)

                        {

                              for(int i=0; i<_bc.Length; i++)

                              {

                                    if ( _bc[i] is packageConfiguration)

                                    {                            

                                          lstPackages.Items.Add(_bc[i].defaultName.value.ToString());                        

                                    }

                              }    

                        }

                  }

 

 

 

This will require the CognosSDK.cs object to be instantiated in order to access the getObjects() method.

 

public baseClass[] getObjects(contentManagerService1 _cmService, string _path, string _package)

 

Cognos SDK Guide by BI Centre -- web.config

Here is a concise definition for a web.config file from wikipedia.

Source:  wikipedia

“The web.config is the main settings and configuration file for an ASP.NET web application. The file is a text based XML document that defines such things as connection strings to any databases the application uses, the default language for child pages, whether debugging is allowed and how it can be implemented, whether session state is used by default, what type of authentication is used, if any, and so on.

Web.config files can only be placed inside directories that have been configured as ASP.NET applications, commonly the web application's root directory. Web.config files inherit properties from higher level .config files and ultimately machine.config however some settings inside machine.config cannot be overridden.

The web.config file is so central to the ASP.NET framework that when the file is saved, IIS restarts the application it belongs to. Visual Studio will automatically create a web.config file when needed, such as compiling a web application to run in debug mode.”

Our web application will be mainly using the web.config for storing the default login credentials for an Administrator user, the dispatcher value and the includes folder for any JavaScript or images.

 

<appSettings>

      <add key="CTSpwd" value="admin1234" />

      <add key="CTSuid" value="administrator" />

      <add key="CNmspace" value="1101" />

      <add key="CCurl" value="http://server/cognos8/cgi-bin/cognosisapi.dll?b_action=xts.run&amp;m=portal/cc.xts&amp;CAMUsername=CC_UID&amp;CAMPassword=CC_PWD&amp;h_CAM_action=logonAs&amp;CAMNamespace=CC_NM" />

      <add key="CognosSDKPathIncludes" value="http://server/cognos8/" />

      <add key="CognosDispatcher" value= "http://server:9300/p2pd/servlet/dispatch" />

      <add key="CSTypePkg" value="packageConfiguration" />

      <add key="CSTypeRpt" value="report" />

</appSettings>

 

 

The C# code uses the following syntax to retrieve the value stored in the web.config.

 

_dispC8 = ConfigurationSettings.AppSettings["CognosDispatcher"];

 

You can see that this value corresponds to the web.config setting.

 

<add key="CognosDispatcher" value= "http://MyServerName:9300/p2pd/servlet/dispatch" />

 

 

Exception Handler Class -- Exhandler.cs

ExHandler.cs is used to handle SOAP Exceptions that may be encountered when making Cognos service requests.  The ExHandler.cs class allows you to display a meaningful error message to the end user.  It captures the severity, error code, message and details of the exception that has been encountered.  These values are appended and returned as a string.

 

This is example code to capture the Exception’s severity.

 

/// Return the exception severity. ///

public string Severity{

      get{

            XmlNode severityNode = exSoap.Detail.SelectSingleNode( "//severity");

                  if (severityNode != null)

                  {

                        return severityNode.InnerText;

                  }

                       

return "";

                 

}

}

 

 

 

Your web solution should have all of it’s TRY-CATCH statements updated in order to reference the functionality ExHandler.cs class file.  You would simply have to instantiate the object in your updated Catch statements.

 

ExHandler exCognos = new ExHandler(exSoap);

 

 

Here is a more detailed example showing the updated Catch statement and appending a string object with the full exception message.

 

try

                  {

                        _cmService = new contentManagerService1();

                        _rptService = new reportService1();

 

                        _dispC8 = ConfigurationSettings.AppSettings["CognosDispatcher"];

                        _NmSpace = ConfigurationSettings.AppSettings["CNmspace"];

                        _Pwd = ConfigurationSettings.AppSettings["CTSpwd"];

                        _Uid = ConfigurationSettings.AppSettings["CTSuid"];

                        _CSTypePkg = ConfigurationSettings.AppSettings["CSTypePkg"];

                        _CSTypeRpt = ConfigurationSettings.AppSettings["CSTypeRpt"];

 

                        _cmService.Url = _dispC8;

                        _rptService.Url = _dispC8;

 

                        _cogSDK = new CognosSDK();

 

                        _cogSDK.CognosLogon(_cmService,_NmSpace,_Uid, _Pwd);

                        _rptService.biBusHeaderValue = _cmService.biBusHeaderValue;

                  }

 

                  catch (SoapException exSoap)

                  {

                        ExHandler exCognos = new ExHandler(exSoap);

                        _ErrMsg = exCognos.Details + " :-: " + exCognos.Message +  " :-: " + exCognos.Severity +  " :-: " + exCognos.ErrorCode;

                  }

                  catch (Exception ex)

                  {

                        _ErrMsg = ex.Message.ToString();

                  }    

 

 

 

 

CognosSDK.cs -- Helper Functions

Your Cognos SDK class will also contain several helper functions that will aid you in querying and executing against the Cognos 8 Content Store.  One example is the sample code to resolve a report’s prompt page prompts and pass the final parameter collection a Report Service’s .run method.  The purpose of the method is to iterate through the prompt page’s form collection and identify all Cognos 8 prompt controls by name and retrieve their associated value.  This method requires that your Cognos 8 Report Author follows a standardized naming convention for the Report Studio prompt pages.  For example, our sample Report Studio reports will name all of the prompt page prompts in the following manner.

 

v      Date Time prompts – p_dteStartDate

v      Value prompt – p_txtFirstName

v      Multiple Select prompt – p_lstCity

 

NOTE:  As you progress through the code in the CognosSDK.cs file you will find references to string functions that rely on this naming convention.  You may be forced to alter your CognosSDK.cs code to work with your Cognos 8 Report Studio naming standards.

 

For example:

 

_promptType = nvcFormData.Keys[x];             

int _posPrompt = _promptType.LastIndexOf("p_");

                 

if (_posPrompt == 2)

{

      _promptName = _promptType.Substring(2, _promptType.Length - 2);

      _promptType = _promptType.Substring(_posPrompt + 2,3);

}

CognosSDK.cs -- Request Report Parameters

A Cognos Report Studio developer can design a report to apply specific filtering on a data item. For example, if a report developer wanted to only return all sale orders that occurred in the city of London then they could design a prompt page that allowed a user to select London as the city parameter item. The sales order query would be filtered based on the selected parameter value.

Knowing the parameters that exist in the report definition is a vital piece of information when executing Cognos Report Studio reports via the Cognos SDK. If the parameter collection is not satisfied then the report will maintain a state of prompting.

Here is a code example that shows the request for a report’s parameter collection. You should not that the report item is an input parameter contained in the search path for the report.

public asynchDetail[] GetParams(string packageName, string reportName, reportService1 rptService)
{
try
{
searchPathSingleObject spSingle = new searchPathSingleObject();
string _pkgName = packageName;
string _rptName = reportName;

spSingle.Value = "/content/package[@name='" + _pkgName + "']/report[@name='" + _rptName + "']";


asynchReply _resParameters = rptService.getParameters(spSingle, new parameterValue[]{},new option[]{});

asynchDetail[] _details = _resParameters.details;

return _details;
}

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


Now that you have asynchDetail[] object you can access the report’s parameter collection information.

CognosSDK.cs -- 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);

}