Purpose of Document
This article introduces two new features added to IBM Cognos Workspace in version 10.2.1.1 - embedding workspaces and passing parameters to workspaces. It also provides sample code for an example application showing integration with the Google map API.
The features used in this article are only available in IBM Cognos Workspace version 10.2.1 FP1 (10.2.1.1) and up.
Exclusions and Exceptions
This document does not cover the details around authentication, security, and single sign on (SSO) between the host or container application and the IBM Cognos 10 BI server that that workspace is created on.
Embedding a workspace from Cognos Workspace and using the parameter-passing API
Embedding analytics and business intelligence dashboards can provide value in various context and applications. When the workspaces are embedded in another application, it is important to be able to set the context so that the workspace’s content can be customized and show the content that is relevant to the users’ context and other content in the container application. In this article, we show an example of embedding a workspace from Cognos Workspace. In addition, we discuss how to pass parameters to the workspace to filter the parameterized Cognos 10 BI reports that it uses.
Introduction to the new features
The two new features introduced in this article are,
- Sharing and embedding a workspace.
- Passing parameters to Cognos Workspace.
The Share Workspace option constructs a URL to the IBM Cognos workspaces and specifies the UI elements that you want to include in the shared or embedded workspaces.
- Open the workspace that you want to share.
- On the toolbar, click Share Workspace. Alternatively, from the Actions menu, click Share Workspace.
Figure 1 - Invoking the Share Workspace dialog from either the application bar or the Actions menu
- Select the display options that you want to share. You can share or hide the following elements,
- Application bar
- Global area
- Content pane (sidebar)
- Tabs. Clear the Tabs box to share only the first tab in your workspace. If the box is selected, all tabs are shared.
- Collaboration pane, if previously set up.
Figure 2 - The Share Workspace dialog box with options to hide various UI elements
- When finished, the URL will be located in the Copy this link and provide... section. Share the link with other users, embed it in a web page, or send the link to another user in an email.
When the URL is constructed, a parameter called remUI will be added to the end of the URL when UI elements are hidden. For example, the following code will remove all the UI elements and only keep the content visible to the users,
To embed a workspace in another web-based application, copy the workspace URL from the Share Workspace dialog and refer to the generated URL in an HTML
<iframe> element using the following format,
<iframe id="embeddedWorkspace" height="600px" width="600px" frameBorder="0" src="workspaceURL">
On a secured server, users must log on unless the web-based application that is pointing to the URL uses single sign-on with the IBM Cognos 10 BI server. Pass the username and password with the URL using the following format,
It should be noted that credentials sent on a URL are sent in clear-text unless SSL (Secure Sockets Layer) communications have been implemented on the IBM Cognos Gateways. There are approaches that you can use to set up single sign-on however authentication is outside the scope of this article. For detailed information about authentication and single sign-on in IBM Cognos 10 BI, see the Resources section at the end of this article.
Passing parameters to Cognos Workspace
In Cognos Workspace version 10.2.1.1 and later, you can pass parameters to Cognos Workspace using the same API that you use to pass parameters to IBM Cognos Viewer.
As illustrated in Figure 3, these parameters are passed to the Cognos Viewer widgets (reports and global prompts) that are used in the workspaces and set the parameter values. For this approach to work you must use parameterized reports in the workspaces and the parameters passed in the URL have to match the parameters used in the reports. For example, if the parameter used in the report is “country”, the parameter passed in the URL must be called “p_country”. In general, the URL parameters have to follow the p_* convention where the * is the name of the parameter(s) used in the report.
Figure 3 - Share workspace dialog with options to hide various UI elements
You can pass either a single value or multiple values as the parameter value. This depends on the report design and the expected behavior. For example, in order to add the value 1153 for the parameter called OrderNum, append the string
&p_OrderNum=1153 at the end of the workspace URL. To pass multiple values you must add encoded XML to the parameter’s value. The example in this article uses this approach.
For more information about the API, passing parameters, and the possible values that you can pass, see the links in the Resources section at the end of this document.
Example scenario – Workspaces from Cognos Workspace and a Google map embedded on an HTML page
Figure 4 shows an example of how to use the two features introduced above to create a custom data driven application on top of the Cognos BI platform. In this example, two workspaces from Cognos Workspace are used. One of the workspaces is embedded in an iframe on the HTML page and the other one is embedded in an iframe on the Google map flyout.
Both of these workspaces use parameterized reports. The workspace that is embedded on the Google map flyout always shows the data related to the country that you selected by clicking on its associated red pin. The workspace on the right side of the page starts with an initial set of countries but you can add more countries to the list by clicking on the Add to list link on the flyout.
The code that comes with this article, googlemap.html, shows how you can build a custom application like this.
Figure 4 - Cognos Workspace dashboards and Google map embedded on an HTML page
To use this example as a starting point, follow the steps below. The example uses the sample Sales and Marketing cube (sales_and_marketing.mdc) and the IBM_Cognos_PowerCube.zip deployment file. Please deploy the IBM_Cognos_PowerCube deployment and make sure the reports run before continuing.
- From the reports.zip file, copy the file googlemap.html into the
- In the attached reports.zip file, open RS_Flyout_reportspec.txt in a text editor such as Notepad, Notepad++ or vi and copy all the content.
- Launch Report Studio.
- Go to Tools > Open report from Clipboard.
- Check to see the report validates and runs. The report goes against the Sales and Marketing (cube) package.
- Save the report as RS_Flyout.
- Close Report Studio.
- In the attached reports.zip file, open RS_rightside_reportspec.txt in a text editor such as Notepad, Notepad++ or vi and copy all the content.
- Repeat steps 3-5.
- Save the report as RS_Rightside.
- Close Report Studio.
- Open Cognos Workspace.
- Select Create New.
- In the content tab, find the RS_Flyout report.
- Click and drag RS_Flyout report to the top left corner of the Workspace canvas. Alternatively you can click and drag the Combination Chart1 and Crosstab1 to the top left corner of the canvas.
- From the Actions menu, click on Save as and name this workspace WS_Flyout.
- From the Actions menu, click on New.
- In the content tab, find the RS_Rightside report.
- Click and drag RS_Rightside report to the top left corner of the Workspace canvas. Alternatively you can click and drag the Crosstab1 and Chart to the top left corner of the canvas.
- From the Actions menu, click on Save as and name this workspace WS_Rightside.
- Edit the googlemap.html file using an editor and search for [UPDATE] to find the two URLs that you need to update. These URLs have to point to the workspaces in your environment.
- One of the URLs set the value of
_rightSideDashboardbaseURL. Use the WS_Rightside shared workspace URL here.
- The other URL sets the value of
_flyoutBaseURL. Use the WS_Flyout shared workspace URL here.
- Launch the page directly using your browser. For example, if your server is called “servername” and your gateway uses the default ibmcognos name, the URL will be http://<servername>/ibmcognos/googlemap.html.
- Passing parameters using IBM Cognos Viewer URL API
- IBM Cognos BI Authentication and Single Sign-On