IBM Business Analytics Proven Practices: Embedding and Passing Parameters Using Workspaces From IBM Cognos Workspace

Product(s): IBM Cognos Workspace; Area of Interest: Reporting

This article introduces two new features added to IBM Cognos Workspace in version 10.2.1.1 - embedding workspaces and passing parameters to workspaces.

Alireza Pourshahid, Software Development Manager, IBM

Alireza Pourshahid is a Software Development Manager within the IBM Cognos team. He is primarily responsible for the development of IBM Cognos Workspace. Ali has been involved in development of IBM Cognos BI products since 2007.



12 December 2013

Also available in Russian

Introduction

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.

Applicability

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.

Assumptions

You are expected to be familiar with IBM Cognos Workspace, parameterized reports and have at least some level of experience with HTML and JavaScript.


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.

Workspace sharing

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.

  1. Open the workspace that you want to share.
  2. 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
    Figure 1 - Invoking the Share Workspace dialog from either the application bar or the Actions menu
  3. 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
    Figure 2 - The Share Workspace dialog box with options to hide various UI elements
  4. 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,

&remUI=banner,sidebar,tabs,globalarea,collaboration

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,

&CAMNamespace=namespace&CAMUsername=user&CAMPassword=pass

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
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
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.

  1. From the reports.zip file, copy the file googlemap.html into the <c10_location>/webcontent folder.
  2. 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.
  3. Launch Report Studio.
  4. Go to Tools > Open report from Clipboard.
  5. Check to see the report validates and runs. The report goes against the Sales and Marketing (cube) package.
  6. Save the report as RS_Flyout.
  7. Close Report Studio.
  8. 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.
  9. Repeat steps 3-5.
  10. Save the report as RS_Rightside.
  11. Close Report Studio.
  12. Open Cognos Workspace.
  13. Select Create New.
  14. In the content tab, find the RS_Flyout report.
  15. 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.
  16. From the Actions menu, click on Save as and name this workspace WS_Flyout.
  17. From the Actions menu, click on New.
  18. In the content tab, find the RS_Rightside report.
  19. 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.
  20. From the Actions menu, click on Save as and name this workspace WS_Rightside.
  21. 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.
  22. One of the URLs set the value of _rightSideDashboardbaseURL. Use the WS_Rightside shared workspace URL here.
  23. The other URL sets the value of _flyoutBaseURL. Use the WS_Flyout shared workspace URL here.
  24. 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.

Download

DescriptionNameSize
Code samplereports.zip9KB

Resources

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
ArticleID=956761
ArticleTitle=IBM Business Analytics Proven Practices: Embedding and Passing Parameters Using Workspaces From IBM Cognos Workspace
publish-date=12122013