Purpose of Document
At the end of this document you will have integrated IBM Cognos 10.2.1 web parts into your Microsoft SharePoint 2010 website.
This document applies to IBM Cognos BI 10.2.1, Microsoft SharePoint 2010 and Microsoft Windows Server 2008 R2 64-bit.
Exclusions and Exceptions
Before getting started, IBM Cognos BI 10.2.1 configured with an Active Directory (AD) namespace using single sign-on (SSO), Microsoft SharePoint 2010, Microsoft Windows and Microsoft Internet Information Service (IIS) 7.x should be installed, configured and running.
Note: If IBM Cognos BI is installed on a separate machine from Microsoft SharePoint, an IBM Cognos Gateway component will need to be installed on the Microsoft SharePoint server and a set of IIS virtual directories should be created for IBM Cognos under the Default Website in order to be used for the WSDL link for Microsoft SharePoint.
Setting up IIS 7.x virtual directories for IBM Cognos BI
- Open IIS Manager.
- At the Server level in IIS Manager, double click on ISAPI and CGI Restrictions in the center console under the IIS header (see Figure 1).
Figure 1 – Selecting ISAPI and CGI Restricions option at the server level in IIS Manager
- As shown in Figure 2, click on Edit Feature Settings in the Action pane and put a checkmark to allow unspecified modules to execute for both CGI and ISAPI. Click OK.
Figure 2 – ISAPI and CGI restrictions content view in the IIS Manager console
- Under the Connections pane click on Application Pools.
- Under Actions click Add application pool.
- Give the application pool a name and click OK. In this example, the name of the application pool is “Cognos” (see Figure 3).
Figure 3 – Add Application Pool dialog from the IIS Manager console
- Once this is completed, right click on the new application pool that you created and select Advanced Settings.
- As shown in Figure 4, change the Enable 32-Bit Applications setting to true. Click OK.
Figure 4 – Advanced settings dialog for an application pool showing the Enable 32-bit Applications property set to true
Note: This should only be set for 32 bit versions of Cognos 10.2.1 and any other pre 10.2.1 version of Cognos as those gateways are not 64-bit.
- In the Connections pane in IIS Manager, right click on the Default Web Site and select Add Virtual Directory. The list of web sites might have to be expanded if you do not see the Default Web Site entry.
- Give an alias name for the virtual directory and point the physical path to the webcontent sub-directory of the IBM Cognos BI install directory as depicted in Figure 5. Click OK.
Figure 5 – Add virtual directory dialog from the IIS Manager console
- Right click on the new virtual directory (“Cognos” in this example) and select Add Application. Give the alias name of cgi-bin. Point the application to the new application pool created in the previous step and point the physical path to the cgi-bin sub-directory of the IBM Cognos BI install directory as shown in Figure 6. Click OK.
Figure 6 – Add application window from the IIS Manager console
- Click on the cgi-bin virtual directory then click on Handler Mappings.
- Select Add module mappings and add a module for cognosisapi.dll file. The values to specify in the fields for the Add Module Mapping dialog are as follows and shown in Figure 7,
Request Path: *.dll
Executable (optional): cognosisapi.dll in the cgi-bin sub-directory of the IBM Cognos BI install
Figure 7 – Add module mapping dialog from the IIS Manager console
- Click on Request Restrictions, go to the Access tab and select Execute (see Figure 8).
Figure 8 – Request restrictions window for the Module Mapping showing Execute selected under the Access tab
- Click OK twice. IIS Manager may prompt you asking if you want to allow ISAPI extensions to execute. Select Yes.
- Back in IIS Manager, click on the Server level and under the Actions menu click Restart.
- Once the restart is complete, open Windows Explorer and go to the cgi-bin sub-directory of the IBM Cognos BI install directory. Locate the web.config file and open it in a text editor such as Notepad.
- Edit the web.config file to add allowPathInfo=”true” to the
<add>element for the handler named “Cognos-Isapi”. Before the change it will look like this,
<handlers> <add name="Cognos-Isapi" path="*.dll" verb="*" modules="IsapiModule" scriptProcessor="E:\Cognos\C10.2\cgi-bin\cognosisapi.dll" resourceType="Unspecified" requireAccess="Execute" preCondition="bitness64" /> </handlers>
After the change, it should look like this,Note: If the web.config file does not exist, you will need to make this change in the \Windows\System32\inetsrv\config\applicationHost.config file.
<handlers> <add name="Cognos-Isapi" path="*.dll" verb="*" modules="IsapiModule" scriptProcessor="E:\Cognos\C10.2\cgi-bin\cognosisapi.dll" resourceType="Unspecified" requireAccess="Execute" preCondition="bitness64" allowPathInfo="true"/> </handlers>
- Save the modified web.config file and exit the text editor.
- Go back to IIS Manager and do a restart at the server level to commit the change.
Copy the Cognos Web Parts files to IIS root
Navigate to the <cognos_install>\cps\SharePoint directory and select all the files listed in Table 1 and copy them to the wwwroot\wss\VirtualDirectories\80 directory under the IIS root directory (usually c:\inetpub).
Table 1- Source and destination folder locations for the Cognos Web Part files
|File||Cognos SharePoint Directory||IIS HTTP Root Directory|
Set up the IBM Cognos security trust file
The Cognos Web Parts use the .NET Web Services stack and they require a higher security trust level than the default minimum security. A sample of a security trust file named wss_cognostrust.config.sample is provided. This file specifies the required security trust, named WSS_Cognos, for the Cognos Web Parts.
Use the wss_cognostrust.config.sample file provided for your version of SharePoint to set up the security trust for the Cognos Web Parts. For a simple SharePoint Portal Server installation, the file can be used without any changes. For more complex installations, you may need to edit this file.
If you already have a trust file used by other Web Parts in your SharePoint Portal Server, you can add the Cognos-specific information from the sample to the existing file so that it can also be used by the Cognos Web Parts.
- Navigate to the \Cognos\c10\cps\SharePoint SharePoint\config\wss.2007 folder and copy the file wss_cognostrust.config.sample to the \Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\CONFIG directory.
- Rename the wss_cognostrust.config.sample that was just copied into the \Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\CONFIG directory to wss_cognostrust.config.
Modify the .NET Framework web.config file
Special attention needs to be taken when updating the file as there are differences in what is recommended as web.config changes by IBM to what is actually required to be done.
Microsoft .NET Framework provides a configuration file named web.config. This file, located in the IIS HTTP root directory, is used to configure the SharePoint services at the application level. To configure the Cognos Web Parts, you must add configuration information to this file.
IBM Cognos 10 provides a sample configuration file named web.config.sample that shows a typical, fully functional configuration of the Cognos Web Parts with a SharePoint portal. You can use this sample to copy snippets of code and paste them into the web.config file. However, do not copy the entire sample file directly to your IIS environment.
To configure the Cognos Web Parts with your SharePoint Portal Server, edit the web.config file by adding the IBM Cognos configuration information. The default folder for web.config is C:\inetpub\wwwroot\wss\VirtualDirectories\80.
There are a few configurations that need to be made and some references to be added - the attached web.config file has all the added configurations required for this to work and they are contained within IBM Cognos comment tags. These will need to be added to your web.config file. At the bottom of the file is the Cognos configuration section where you will need to input the appropriate connection information. The cps_auth_namespace will need to be updated for single sign-on (SSO) to work and you will need to add the password and whether or not you need to exclude the domain.
<!-- IBM COGNOS \\\\\\\\\ --> <Cognos> <Log filename="C:\Cognos.BI.WebPart.log" error="true" warn="true" info="true" debug="true" performance="true" /> <!-- SoapLog filename="C:\Cognos.BI.WebPart.SOAP.log" / --> <SSO cps_auth_namespace="Namespace ID" cps_auth_secret="Password" excludeDomain="true" /> <PortalContext gatewayURL="http://servername:81/Cognos/cgi-bin/cognosisapi.dll" webContentURL="http://servername:81/Beta" /> <Fault stacktrace="false" /> <HttpClient timeout="15000" /> </Cognos> <!-- IBM COGNOS ///////// -->
Once the web.config file has been updated, open a command window and run the iisreset command to restart IIS. The CPS namespace and password are configured in Configuring Portal Services section of this document.
Edit the Cognos Web Parts catalog files
This section will guide you through the editing of the solution file for the purpose of building and deploying the solutions file to the Microsoft Sharepoint website in order to view the IBM Cognos Portlets.
- Navigate to the \Cognos\c10\cps\SharePoint SharePoint\solution directory.
- Open the build.properties file in a text editor and change the following entries,
- gateway.wsdl.url - set this to your gateway URI. If using SSO, make sure it works from the SharePoint server. You may need to use an alternative URL from the server, such as localhost instead of the machine name.
- authentication.sharedSecret - only if you used it.
- authentication.namespace - the primary authentication namespace ID.
- authentication.excludeDomain - needs to match the web.config.
- webcontent.url - points to your webcontent location for your gateway.
- gateway.url – the full gateway URL.
- Once these have all been updated correctly, save the file and run the build.bat file.
- Once the batch file finishes executing navigate to the \Cognos\c10\cps\SharePoint SharePoint\solution\package directory. You will see the ibmcognos_webparts.wsp file. Copy it and then paste it into the C:\inetpub\wwwroot\wss\VirtualDirectories\80 directory.
- From the Start Menu, navigate to Microsoft SharePoint 2010 Products and open the SharePoint 2010 Management Shell.
- When the window opens, navigate to the C:\inetpub\wwwroot\wss\VirtualDirectories\80 directory and run the following command,
stsadm -o addsolution -filename ibmcognos_webparts.wsp
If you have done these steps before and need to update the existing solutions file in SharePoint, you will need to execute the following command in the SharePoint 2010 Management Shell,
stsadm -o upgradesolution -name ibmcognos_webparts.wsp -filename ibmcognos_webparts.wsp -local –allowCasPolicies -allowGacDeployment
Add Cognos Portal Service security namespace for SSO
This section is a guide for setting up the Cognos Portal Service (CPS) namespace for the purpose of using SSO through Microsoft Sharepoint to the IBM Cognos Portlets.
- Open IBM Cognos Configuration for your Content Manager and create a new security namespace. Give it the name cps_trust and select the type Custom Java Provider.
- As shown in Figure 9, set the Namespace ID to cpstrusted and the Java class name to com.cognos.cps.auth.CPSTrustedSignon.
Figure 9 – Setting up the CPS security namespace in IBM Cognos Configuration
- Save the configuration.
Configuring portal services
In IBM Cognos Configuration you will also need to configure the Portal Services section for the following properties that are highlighted in Figure 10,
- Web Content URI – This is the main URI to IBM Cognos BI. For example, http://servername:80/RP1.
- Location of applications.xml – Ensure that the server name is correct.
- Trusted Signon Namespace ID – Set this to namespace ID that SharePoint uses.
- Shared secret – Set this to the same value as the Shared Secret password that was set in SharePoint.
Figure 10 – The Portal Services properties section in IBM Cognos Configuration
Once this is complete, save the configuration changes.
Setting allowances for the Cognos Application Firewall (CAF)
In order for IBM Cognos and Microsoft Sharepoint to be integrated fully the IBM Cognos CAF valid domains and hosts list will need to be updated in order to allow the IBM Cognos Portlets to access content through the Microsoft Sharepoint Portal.
- You need to add localhost and the machine name to the valid domains list for both port 80 and the port for your default web site (for example, port 81). As shown in Figure 11, click on the Valid domains or hosts property and enter the required values.
Figure 11 – Setting valid domains or hosts in the IBM Cognos Application Firewall properties section in IBM Cognos Configuration
- Save the changes and restart IBM Cognos BI.
Deploying the solution file in SharePoint
This section will guide you through the process of adding the solution file generated earlier in this document to the Microsoft Sharepoint solutions farm, so that IBM Cognos Portlets can be added to Microsoft Sharepoint Pages.
- From the Start Menu on the SharePoint server, select Microsoft SharePoint 2010 Products and then select SharePoint Central Administration.
- When the window opens, select System Settings, then under Farm Management select Manage farm features (see Figure 12).
Figure 12 – Manage farm features using SharePoint Central Administration
- As shown in Figure 13, in the new window, you will see the ibmcognos_webparts.wsp file. Click on the filename to get the various options.
Figure 13 – Selecting the Cognos web part solution in SharePoint Central Administration
- Select Deploy Solution (Figure 14).
Figure 14 – Selecting the Deploy Solution option in SharePoint Central Administration
- As highlighted in Figure 15, in the drop down menu for the Choose a Web application to deploy this solution: field, select your SharePoint site on port 80 (it should just show the machine name with no port) and then click OK. It will then deploy the file.
Figure 15 – Selecting the SharePoint site to deploy a solution to using SharePoint Central Administration
- Once the deployment process has completed, it will take you back to the previous page and say that it is deployed.
Adding a portlet to a SharePoint page
This section guides you through the basic setup of adding IBM Cognos Portlet Webparts to a Microsoft Sharepoint Page. All steps are done on the Microsoft Sharepoint side.
- Open your SharePoint site on port 80. The URL to do this should be http://servername.
Figure 16 – The home screen on the SharePoint Main site
- From the Site Actions dropdown in the top left corner, select . You will be asked to give the new page a name and an alias. Click OK and the new page will open.
- As shown in Figure 17, to the left of the Browse tab there is an Edit button. Click on the Edit button.
Figure 17 – Edit the new Cognos page on the SharePoint Main site
- You will now have the editing toolbar at the top. As shown in Figure 18, under the Editing Tools header, select the Insert tab.
Figure 18 – The Insert tab under the Editing Tools section on SharePoint Main site
- Click on Web Part to get the web part options (see Figure 19).
Figure 19 – Select the Web Part to insert into the new Cognos page
- As per Figure 20, click on the Miscellaneous folder, select IBM Cognos Navigator and click the Add button.
Figure 20 – Selecting the IBM Cognos Navigator Web Part from the Miscellaneous folder and adding it to the new Cognos page
- To edit the IBM Cognos Navigator options, click on the drop down in the top right corner and select Edit preferences (see Figure 21).
Figure 21 – Editing the preferences for the IBM Cognos Navigator Web Part
- You will be presented with the IBM Cognos Navigator properties window similar to the one shown in Figure 22.
Figure 22 – The IBM Cognos Navigator properties window
|web.config with added configuration||web.zip||10KB|
Dig deeper into Big data and analytics on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Tools, technologies, and software for building enterprise analytics solutions.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.