[updated 1/9/23 to include cross-site advanced parameter step.]
In recent months, we've had several customers ask an age-old question: How do I embed a dashboard into my webpage?
Many of you reading this might have used the technique in this blog in the past against Cognos Reporting objects. If you have, you'll recognize these steps! But - Did you know this is also possible using Cognos Analytics Dashboards as well?
BTW - there are other methods to achieve embedding Cognos dashboards, such as using the Cognos Dashboard Embedded service available in the IBM Cloud Catalog, so if this blog isn't a match for you, check out the IBM Cloud Catalog or contact your IBM account representative. However, this example uses the good-ole-fashioned, simple technique leveraging Parameterized URLs.
Before getting started, I should caveat that this technique was written up by field practitioners, not by any formal party inside of IBM. It is illustrated here simply for the “sharing of creative ideas with like-minded folks,” and does not imply a promise of support, services, or capability. That said, everything we've done here is documented in the IBM Cognos Analytics 11.1.x product manual.
THE BUSINESS USE CASE
We are using IBM Cognos Analytics on Cloud Hosted (w/Capacity-based Entitlements) on release 11.1.7 and would like to make one of our dashboards (built using Cognos Dashboard) available on our public website so anyone in the world can view it. Can this be done?
OUR ANSWER USING PARAMETERIZED URLS
Yes, Curious Cognoid, while there are different ways to achieve this, it is certainly possible. We have created an example with steps below to illustrate this using parameterized URLs.
Since the public (not one of your employees) will be viewing this dashboard, you will need an anonymous log on ID. However, you are using one of IBM’s Software-as-a-Service cloud offerings where the official “allow anonymous” feature is not available (as of the original date of this blog post anyway).
This means two things:
- You must have capacity based entitlements to allow anyone in the public to view it. If you have entitlements based on number of users, only those users with a Cognos userid and login may view it.
- You will need an all-purpose, generic user ID created that only has privileges to view the intended dashboard and nothing else. We will be passing this generic ID to Cognos so that the public user does not get prompted to log on. FYI - Every public user that views this dashboard will be using this generic ID behind-the-scenes (and yes, multiple people can be logged in using this ID at the same time).
SO LET'S GET TO IT!
Requirements to perform this example:
- Cognos Analytics on Cloud Hosted/Dedicated environment version 11.1.7
- Capacity-based entitlements (not number of named seats*)
- Standard IBM Samples installed (California website visits dashboard)
- An all-purpose, generic user ID and password
- A draft company webpage (or some portal where you are embedding this)
*note: If you have entitlements based on number seats, you can still embed the dashboard, but person viewing the dashboard on your webpage will need a Cognos username and password. If doing this, you will only need to perform step 3 and 6 below and skip everything else related to the advanced variable and the CAM parameters.
Steps to embed a Cognos Dashboard into a publicly available website:
- Add an advanced parameter (Glass.urlLoginParameters) to System>Advanced Settings with values set to CAMNamespace, CAMUsername, CAMPassword. This will allow you to pass the authentication namespace, username, and password through a parameterized URL.
If you are not using Release 11.1.7 of Cognos, the instructions for the advanced parameters may be different or may not be needed.
Update 1/9/2023: If you receive a logon error after implementing the steps in this blog, you may need to add an additional advanced parameter (Configuration.cookieSameSite) with None in the value field. If this is the case for you, please see the additional step here: Setting SameSite attribute on cookies.
- Open the Properties > “Share” for the dashboard you are embedding.
- Copy the Link URL to embed into your webpage (or the embed iframe code, if using iframe to embed).
- At the end of the URL, append:
Note: If you only have one namespace, you might not need the CAMNamespace parameter as it should default to it.
Also, you can play with adding additional parameters to remove/add toolbars, such as &ui_appbar=false&ui_navbar=false. See this page for more info on optional parameters.
- Substitute the following in the above url:
- where it says mynamespacename, add your namespace instead
- where it says myusername, add your username instead
- where is says mypassword, add your password instead
Here's what it looked like for me - yours should be similar:
- If just URL needed (with toolbars displayed):
- If just URL needed (without toolbars displayed):
- If using the iframe code (note, I changed the width and height values to 1000):
<iframe src="https://mycognosurl/bi/?perspective=dashboard&pathRef=.public_folders%2FSamples%2FDashboards%2FCalifornia%2Bwebsite%2Bvisits&closeWindowOnLastView=true&ui_appbar=false&ui_navbar=false&shareMode=embedded&action=view&mode=dashboard&CAMNamespace=LDAP&CAMUsername=myusername&CAMPassword=mypassword" width="1000" height="1000" frameborder="0" gesture="media" allow="encrypted-media" allowfullscreen=""></iframe>
- Add your URL or iframe code to your webpage or portal technology as you see fit.
Here's the result!
If I set the application and navigation parameters to true (or simply leave out the parameters), it would be embedded like this:
But I don’t really want the application bar and navigation bars to appear. So, I removed them by ensuring the parameters are set to false.
- Append &ui_appbar=false&ui_navbar=false to the URL
- Add the updated URL or iframe code to your webpage or portal as needed to embed.
And here’s what I end up with - a much cleaner look: