IBM Cognos Proven Practices: IBM Cognos Express SharePoint Configuration

Nature of Document: Tip or Technique; Product(s): IBM Cognos Express; Area of Interest: Infrastructure

A step by step demonstration of how to enable IBM Cognos Express integration with the Microsoft SharePoint portal.

Share:

Haytham Yassine, Software Engineer

Haytham started off his career at IBM as an intern, and was then selected for IBM's Extreme Blue program. Shortly after, he joined IBM's Business Analytics group and was part of the team that designed and implemented IBM Cognos Express. The team managed to successfully release the first all-round mid-market BI solution. Haytham holds a bachelors degree in Software Engineering and Business Management. His areas of interest include Business Analytics, Social Media, and mobile applications. Recently, Haytham has recently moved to IBM's Cognos Consumer Insight, a product that tracks and analyzes user sentiment over the web.



Jane Li, Software Quality Developer , IBM

Jane is a Software Quality Developer with the IBM Cognos Consumer Insight team who possesses years of software development and testing experience. Since joining IBM in 2008, she has developed test cases and scenarios for testing different areas of the IBM Cognos Express and IBM Cognos Consumer Insight products. For these components she was responsible for installation, configuration, functional, globalization and system verification testing on Windows and Linux environments.



04 May 2011

Introduction

Purpose

This document demonstrates step by step how to enable IBM Cognos Express integration with the Microsoft SharePoint portal.

Applicability

The procedures outlined in this document only apply to IBM Cognos Express 9.5 and the Microsoft SharePoint Portal 2007.

Exclusions and Exceptions

Integration with Microsoft SharePoint Portal 2003 and 2010 is not supported in an IBM Cognos Express 9.5 environment and is hence not covered in this document.


Overview

Integrating IBM Cognos express into a Microsoft SharePoint Server requires several configuration changes to both products. A high level overview of all steps required is provided here:

  1. Copy the Cognos Web Parts Resources from IBM Cognos Express Server to the Microsoft IIS content root directory in SharePoint Server
  2. Set up the IBM Cognos security trust file in SharePoint Server
  3. Modify the .NET Framework web.config file in SharePoint Server
  4. Modify the Cognos Web Parts catalog files in SharePoint Server
  5. Restart IIS in SharePoint Server
  6. Enable Single Sign-on Using Shared Secret
  7. Add Cognos Web Parts to a SharePoint page
  8. Customize the content of Cognos Web Parts

Copy the Cognos Web Parts Resources

  1. From Cognos Express server, go to the <cx_install_location>\cps\sharepoint directory.
  2. Make sure you have the specified files from the table below in the <cx_install_location>\cps\sharepoint directory
    Sub folderFile
    /sharepoint/bin/Cognos.BI.WebPart.dll
    /sharepoint/bin/deCognos.BI.WebPart.resources.dll
    /sharepoint/bin/enCognos.BI.WebPart.resources.dll
    /sharepoint/bin/frCognos.BI.WebPart.resources.dll
    /sharepoint/bin/jaCognos.BI.WebPart.resources.dll
    /sharepoint/wpcatalog/CognosNavigator.dwp
    CognosSearch.dwp
    CognosViewer.dwp
    /sharepoint/wpresources/Cognos.BI.WePart/dialog_error.gif
    Note: You may have more localization directories under bin folder.
  3. Copy the bin, wpcatalog and wpresources folders from this directory to the Microsoft IIS content root directory on the Sharepoint Server.
    For example: C:\Inetpub\wwwroot\wss\VirtualDirectories\<portnumber>\
    Note: You may get a warning that you are about to overwrite existing files/folders, but in general these should not be pre-populated and safe to do so.

Set up the IBM Cognos security trust file

  1. Go to the <cx_install_location>/cps/sharepoint/config directory.
  2. Copy the wss_cognostrust.config.sample file: - Copy the file from the <cx_install_location>/cps/sharepoint/config/wss.2007 directory to the C:/Program Files/Common Files/Microsoft Shared/web server extensions/12/CONFIG folder on the Sharepoint Server.
  3. Rename the copied file to wss_cognostrust.config.

Modify the .NET Framework web.config file

Modifying the .NET configuration file

The web.config file is the central configuration point for all .NET Framework applications. Add the following information to the configuration element in this file.

Note: when you edit the file, make sure there is a space between two attributes; otherwise you will get syntax error when you launch the Microsoft SharePoint server.

  1. Go to the IIS HTTP root directory. For example, C:\Inetpub\wwwroot\wss\VirtualDirectories\<portnumber>
  2. Make a copy of the original web.config file in case you need to go back to it, then edit the web.config file as demonstrated in the sections below and save the file.
  3. Open the web.config file in an XML editor.

All modifications listed below are also demonstrated in the web.config.sample file located in the <cx_install_location>\cps\sharepoint\CONFIG folder. It is not recommended to use this file as a replacement to the original web.config file shipped with the SharePoint portal. Instead you can use this sample file as a reference to modifying the original.

All the modifications listed below can be found in the sample file by searching for the following comment tag:

<!-- IBM Cognos \\\\\\\\\ -->

Add the IBM Cognos Configuration Section

In the configSections section, add the following sectionGroup element:

<sectionGroup name="Cognos"> 
<section name="Log" type="System.Configuration.SingleTagSectionHandler, 
System,Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/> 
<section name="SoapLog" type="System.Configuration. SingleTagSectionHandler,System, 
Version=1.0.5000.0, Culffture=neutral, PublicKeyToken=b77a5c561934e089"/> 
<section name="SSO" type="System.Configuration.SingleTagSectionHandler, 
System,Version=1.0.5000.0, 
Culture=neutral, PublicKeyToken=b77a5c561934e089"/> 
<section name="PortalContext" type="System.Configuration. SingleTagSectionHandler, 
System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/> 
<section name="Fault" type="System.Configuration.SingleTagSectionHandler, 
System, 
Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/> 
<section name="HttpClient" type="System.Configuration.SingleTagSectionHandler, 
System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/> 
</sectionGroup>

See the web.config.sample shipped with IBM Cognos Express for an example.

Register the Cognos Web Part Assembly as a Safe Control

In the SharePoint section, add the following SafeControl element to the SafeControls element.

<SafeControl Assembly="Cognos.BI.WebPart, Version=1.0.0.0, Culture=neutral, 
  PublicKeyToken=cb3c72729d0875cd" Namespace="Cognos.Portal.Services"
  TypeName="*" Safe="True"/>

See the web.config.sample shipped with IBM Cognos Express for an example.

Register the IBM Cognos Security Trust File

Cognos Web Parts require the security trust named WSS_Cognos which is defined in the wss_ cognostrust.config file.

In the system.web section, add the following trustLevel element to the securityPolicy element.

<code type="section">
<trustLevel name="WSS_Cognos" 
  policyFile="C:\Program Files\Common Files\Microsoft Shared\
  Web Server Extensions\12\config\wss_cognostrust.config" />

See the web.config.sample shipped with IBM Cognos Express for an example.

Change the Trust Level to WSS_Cognos

WSS_Cognos is the security trust required by the Cognos Web Parts. In the system.web section, change the trust level from

<trust level="WSS_Minimal" originUrl="" />
to
<trust level="WSS_Cognos" originUrl="" />

See the web.config.sample shipped with IBM Cognos Express for an example.

Enable the Session Object

  • In the system.web section, add the following element to the httpModules element if the element does not already exist:
    <add name="Session" type="System.Web.SessionState.SessionStateModule"/>
    Note: If the element is commented out, remove the comments.
  • In the system.web section, add the following element to the httpHandlers element:
    <add verb="*" path="CognosResources/*.axd"type="Cognos.Portal.Services.
       HttpResourceHandler, Cognos.BI.WebPart,Version=1.0.0 Culture=neutral,
       PublicKeyToken=cb3c72729d0875cd" validate="false"/>
  • In the system.web section, add the following pages element.
    <pages enableSessionState="true" enableViewState="true" enableViewStateMac="true"
       validateRequest="false" />
    Note: If this pages element already exists, change the value of its enableSessionState attribute to true.

Register Cognos Portal Services as a SOAP Extension

In the system.web section, add the following webServices element:

 <webServices> 
		<soapExtensionTypes> 
			<add type="Cognos.Portal.Services.SoapPatchExtension,
			  Cognos.BI.WebPart, Version=1.0.0.0, Culture=neutral,
			  PublicKeyToken=cb3c72729d0875cd" priority="1" group="0" /> 
		</soapExtensionTypes> 
</webServices>

The soapExtensionTypes element represents all SOAP extensions that are available to your Web service at run time.

Note: If the webServices and soapExtensionTypes elements are already defined, add only the element that is in bold above.

See the web.config.sample shipped with IBM Cognos Express for an example.

Specify the IBM Cognos Configuration Parameters

Use the Cognos element to specify the IBM Cognos configuration parameters as defined in IBM Cognos Configuration.

Insert the following Cognos element between the closing tags </system.net> and </configuration>:

<Cognos> 
		<SoapLog filename="c:\Cognos.BI.WebPart.Soap.log"/> 
		<Log filename="c:\Cognos.BI.WebPart.log" error="true" warn="false"
		  info="false" debug="false" performance="false" /> 
		<SSO cps_auth_namespace="" cps_auth_secret="" /> 
		<PortalContext gatewayURL="" webContentURL="" /> 
		<Fault stacktrace="false" /> 
</Cognos>

See the web.config.sample shipped with IBM Cognos Express for an example.

The elements inside the Cognos tag represent the different configuration settings.

  • Use the SSO element to specify the IBM Cognos Security Namespace ID of the CPS trusted namespace named cps_auth_namespace and the shared secret password named cps_auth_secret.
    Note: The values set for these two attributes should match what will be set in IBM Cognos Configuration on the IBM Cognos Express server, in section 8.2 and 8.3 below.
    For example, assume the following values were set as reference for steps to follow:
      	cps_auth_namespace="cpstrusted" 
      	cps_auth_secret="mySharedKeyHere"
  • Use the SoapLog element to specify the location for the Web Services log files.
  • Use the Log element to specify a different location for the log file, and to enable the different logging features by changing the attribute values from false to true.
  • Use the PortalContext element to specify the URL attributes for IBM Cognos gateway and IBM Cognos Web content, as shown in the following example:
    PortalContext gatewayURL="http://<cognos_express_host>:<port>/p2pd/servlet/dispatch" 
    webContentURL="http://<cognos_express_host>:<port>/p2pd"
    Note: This parameter is optional and the 2 attributes may be kept blank since they will be configured in IBM Cognos Configuration.
  • Use the Fault element to display the call stacks in the error page when a fault is caught by a Web Part.

Modify the Cognos Web Parts catalog files

The catalog files contain the definitions of the Cognos Web Parts to use in SharePoint Portal Server. For each Cognos Web Part catalog file, change the WSDL URL to point to your IBM Cognos Express dispatcher.

  1. Go to the Microsoft IIS content root directory where the catalog files were copied in Chapter 3 of this document.
    For example, C:\Inetpub\wwwroot\wss\VirtualDirectories\<portnumber>\wpcatalog
  2. In each Cognos Web Part catalog file, Cognos*.dwp, change the URL in the WSDL element to point to your IBM Cognos Express dispatcher.
    Here is an example:
    <WSDL xmlns="http://developer.cognos.com/webpart/v1"> 
    http://<cognos_express_host>:<port>/p2pd/servlet/dispatch/wsrp/cps4/portlets/nav?b_ 
    action=cps.wsdl&amp;wsdl</WSDL>
    Note: The ampersand characters (&) in the URL must be XML-encoded as &amp;
  3. Save the file.

Restart IIS in SharePoint Server

You must restart Internet Information Services (IIS) for the configuration changes to take effect.

  1. From the Sharepoint Server, restart IIS using the management console, or the iisreset.exe command line tool.
  2. The Cognos Web Parts are now available in SharePoint Portal Server, and can be added to the portal pages.

Enable Single Sign-on Using Shared Secret

Single sign-on should be enabled between the IBM Cognos portlets in Sharepoint and IBM Cognos Express. The following steps should be followed:

Configure the Active Directory Namespace for Single Sign-on

If you haven’t done so already, you should configure Cognos Express to use your Active Directory system for authentication. See the Changing the configuration of IBM Cognos Express Manager section in the Managing IBM Cognos Express user guide for details.

Once that is done please follow these additional steps:

  1. On the IBM Cognos Express server machine, stop the IBM Cognos Express service from Windows Services.
  2. Open IBM Cognos Configuration by launching cogconfig.bat located under <cx_install_location>\bin.
  3. In the Explorer window, under Security, Authentication, click the Active Directory namespace you configured.
  4. Click in the Value column for Advanced properties and then click the edit button.
  5. In the Value - Advanced properties dialog box, click Add.
  6. In the Name column, type singleSignOnOption.
  7. In the Value column, type IdentityMapping.
    Screenshot of Cognos Configuration configuring the singleSignOnOption
  8. Click OK in the Value - Advanced properties dialog box.
  9. Click in the Value column cell for Binding credentials, and then click the edit button.
  10. In the Value - Binding credentials dialog box, specify a valid user ID and password in that Active Directory namespace and then click OK. It is highly recommended to use the UPN format (e.g. user@domain.com ) when filling out the user ID.
  11. From the File menu, click Save. Do not close IBM Cognos Configuration yet as it is still needed in the steps to follow.

Create and Configure the Custom Java Provider Namespace

You must create a Custom Java Provider namespace to add the Custom Java authentication provider that is provided with IBM Cognos Express. To do that, please follow these steps:

  1. In the Explorer window of IBM Cognos Configuration, right click Authentication under Security and select New Resource > Namespace…
  2. Specify a name (for example cpstrusted_name) and set the type to be Cognos Express, which is basically a Custom Java Provider. Click OK.
  3. Click in the Value column cell for Namespace ID, and specify a new ID (for example cpstrusted to be consistent with the value set in section 5.8 above). Remember this value should match what was configured on the Sharepoint server as part of Section 5.8.
  4. Click in the Value column cell for Java class name, and type:
    com.cognos.cps.auth.CPSTrustedSignon
  5. From the File menu, click Save. Do not close IBM Cognos Configuration yet as it is still needed in the steps to follow.
    Screenshot of Cognos Configuration configuring the Trusted Signon Provider

Configure Single Sign-on Access to Portal Services

  1. In the Explorer window of IBM Cognos Configuration, under Environment, Portal Services configure the following properties:
    • For Trusted Sign-on Namespace ID, type the Namespace ID of the Active Directory you configured in step 8.1, which is CognosExpressActiveDirectoryID by default.
    • For Shared secret, type the key to be used for single sign-on (for example mySharedKeyHere to be consistent with the value set in step 5.8).
      Tip: Remember this value should match what was configured on the Sharepoint server as part of step 5.8. This parameter represents the authorization secret that must be shared between the Sharepoint server and the IBM Cognos Express server. Consider this as a secret password. You must use the same character string when you configure the portlet application. You must use a single word as a key.
    • Configure access to the Portal Services web content. Set the value for Web Content URI by specifying the host name and port number of the IBM Cognos Express dispatcher in the following format: http://<host>:<port>/p2pd
      Screenshot of Cognos Cognfiguration configuring Portal Services
  2. From the File menu, click Save. Close IBM Cognos Configuration and click No when prompted to start the service before exiting.
  3. Open the file <cx_install_location>\configuration\cogstartup.xml in a text editor. Search for the following xml entry and make sure the values in bold are set as follows.
    <crn:parameter name="overrideNamespace" disabled="false"> 
        <crn:value xsi:type="xsd:boolean">true</crn:value> 
    </crn:parameter>
  4. Save the file if any changes were needed and exit the editor.
  5. Start the IBM Cognos Express service from Windows Services.

Add Cognos Web Parts to a SharePoint page

You can use the Cognos Web Parts to add the IBM Cognos Express content to your pages in SharePoint Portal Server. You can add or remove the Web Parts from the shared view, or from the personal view of the page. Ensure that you are in edit mode before you make changes to the page.

The following steps provide only basic instructions for adding the Cognos Web Parts to SharePoint pages. For more information, see the SharePoint Portal Server help.

We will add web parts for Cognos Viewer, Cognos Navigator and Cognos Search.

  1. Log on to your SharePoint Portal Server with administrative permissions.
  2. Go to the page where you want to add the Cognos Web Parts.
  3. From the Site Actions menu in the upper-right corner, click Edit Page.
  4. In the Web Part zone where you want to add the Cognos Web Part, click Add a Web Part.
  5. In the Add Web Parts dialog box, click All Web Parts, Miscellaneous.
  6. In the Add Web Parts tool pane on the right side of the page, click Server Gallery.
  7. From the list of available Cognos Web Parts, click the Web Part you want (Cognos Viewer, Cognos Navigator and/or Cognos Search).
  8. At the bottom of the tool pane, from the Add to menu, select the location on the page where you want the Web Part to appear, and click the Add button.
    Tip: You can also drag the Web Part to different drop zones in the page.
  9. Repeat steps 4 to 8 for each Cognos Web Part you want to add to the page.
  10. Click Exit Edit Mode.
  11. You can now customize the content of the Cognos Web Parts.

Customize the content of Cognos Web Parts

An administrator can define the default content and appearance for Cognos Web Parts. When users add the Web Part to their pages, the default properties are enabled. For example, in the Cognos Navigator Web Part, the administrator can define the default display folder or package. When users add this Web Part to their pages, they see the folder or package that was specified by the administrator.

Users can change the Cognos Web Part properties to personalize their pages. The changes made by each individual user do not affect other users or other pages. The personalized settings are not affected if the administrator changes the default properties for the Web Part. Users can click the Reset button to revert to the current administrative defaults.

  1. Go to the page in your SharePoint Portal Server that contains the Cognos Web Part you want to edit.
  2. From the Site Actions menu in the upper-right corner, click Edit Page.
  3. In the Web Part that you want to change, click the edit button.
  4. Click Edit preferences. The Web Part properties page appears.
  5. Specify the settings as required.
  6. For more information, click the help button in the upper-right corner of the properties page.
  7. Click OK.
  8. Click Exit Edit Mode.

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=655445
ArticleTitle=IBM Cognos Proven Practices: IBM Cognos Express SharePoint Configuration
publish-date=05042011