Extensions in Cognos Analytics

When compared to Cognos 10, Cognos 11 has a very different portal system. Called Glass, this extensions system allows a much greater flexibility in terms of adding additional buttons and menus. Pretty much every aspect of the portal can be modified, including the ellipsis menus. In addition to adding, we can also prevent users from seeing specific menu items.

1. Opening a webpage in an iFrame
2. Running a report or a dashboard
3. Opening a folder
4. Add a dashboard shape
5. Run a script
6. Adding a menu for any of the above actions
7. Hiding specific glass features or views

Let’s start with a basic extension – opening a website in an iFrame.

  "comment":"Opens the incident reporter in Cognos.",
	"schemaVersion": "1.0",
	"extensions": [
		"perspective": "common",
		"comment": "There is a special meta perspective called COMMON. Adding contributions to this perspective will cause the extension to be applied to All perspectives.",
		"features": [{
			"id": "incidentOpener",
			"toolItems": [
				"comment": "This code will display a custom Website button that opens the specified URL in an iFrame.",
				"id": "ops.iframeOpener.incidents",
				"containerId": "com.ibm.bi.glass.navbarTrailingGroup",
				"label": "Incidents",
				"icon": "images/incidentReporter.png",
				"type": "Button",
				"weight": 100,
        "coachMark":{"title":"Incident Reporter","contents":"Use this link to open new incidents"},
				"actionController": "bi/glass/api/IFrameOpener",
				"options": {
					"url": "http://SERVER/incidentReporter.aspx",
					"title": "Incidents"

Let’s go through this.

Top level has name, schemaVersion, and contains the extensions array. In all places you can add a comment field.
Name should be descriptive so the next person working on this can figure this out. And then use the comment to explain what you’re doing!
Comments are just that, they’re ignored by Cognos and they’re a great place to defend your code.
The extension allows you to handle different perspectives in different ways. So you might want this to appear in one way in authoring, and another way when the user is in dashboards.

Inside extensions we start getting into how the extension appears on the page.
Perspective lets you apply this everywhere (“common”) or to a specific view (“home”, “authoring”, “dashboard”, or “modeller”).
Features defines the items in the extension.

And inside features…
id needs to be unique.
toolItems are the actual buttons and menu structure.

And inside the toolItems…
This is the place where we define what appears in the locations.
Each item needs a unique ID.
The container ID references various places in Cognos. It’s the parent of item you’re creating. The help documentation lists five placement options, but I’ll give you a hint. You can use developer toolbars to examine various elements in Cognos to see if you can put an item there:

You could also do what it says on the IBM article here, but that would be far too easy.

Label and Icon are self-explanatory.
Type can be menu, menuItem, or button. If you have a menuItem, you need to make sure the containerID is a menu. It doesn’t need to be a menu that you’ve created.
Weight determines the position of the item in the container, higher numbers making it have a higher position.
Push turns the button into a toggle.
coachMark is an object containing title and contents that creates those nice blue hint bubbles.
actionController tells Cognos what this button does. The one above opens an iFrame, but you could also use ReportOpener, DashboardOpener, FolderOpener. In my next example further down I’ll show how to run a custom controller.
Options give context to the action. In this case we want the iFrame to open incidentReporter.aspx on SERVER. If you point against an external website please note that not all websites allow themselves to be viewed in iFrames. Google for example just won’t work.

To use it you need to paste the JSON into a file called spec.json. The icon is looking for images/incidentReporter.png. Zip the spec.json and the images folder and you’re done!

Now when we upload it we see the incidents button under the Manage on the bottom left:

Now let’s do something a little more complex fun.

One of things that always bugged me about using Cognos in Chrome was the lack of clipboard access. While it’s true that you can now copy objects from report to report in C11.1, there are times when I want to modify the XML. Local classes, for example, have a very limited list of options. If I want to add something non-standard, like position:absolute, I’d have to open it in IE or copy the entire report XML.

We’re not going to get into the JS behind my Clipboard Editor, but we’ll go into the JSON of the object.

	"schemaVersion": "1.0",
	"extensions": [
		"perspective": "authoring",
		"comment": "This is a collection of extensions aimed at easing the life of a developer.",
		"features": [{
			"id": "CognosPaul.BagOTricks",
			"toolItems": [
				"containerId": "com.ibm.bi.glass.appbarTrailingGroup",
				"type": "Menu",
				"label": "Custom Tools",
				"icon": "images/bag.png",
				"weight": 650
				"id": "custom.appbar.trailingGroup.menuItem2",
        "comment":"Clipboard editor will allow you to copy an object in Cognos and see the XML in a memo input. You can then edit it and paste back into Cognos.",
				"containerId" : "custom.appbar.trailingGroup.trickMenu",
				"comment": "The containerId is the ID of the parent menu.",
				"type": "MenuItem",
				"actionController": "v1/ext/CognosPaul_Bag_o_Tricks/js/controllers/ClipboardEditor",
				"comment": "action controller is looking at the js embedded in the zip.",
				"label": "Edit Clipboard",
				"icon": "images/clipboard.png",

In this case I’m creating a menu in the appbarTrailingGroup. It will appear in the upper right menu bar, next to the ellipsis menu.

The menu named “CognosPaul_Bag_o_Tricks”, and that same name will be used further down in the actionController. It contains one extension, which is only valid from the authoring perspective.

The extension itself contains a menu, and a single menu item. Notice the containerId for both items. The only major difference between this and the iFrame viewer is the actionController. Notice the call is without js, and uses the name of the object: “v1/ext/EXTENSIONNAME/folderstructure/JSFILENAMEWITHOUTTHEJSEXTENSION”.

I personally find the clipboard editor incredibly useful, but because I’m using undocumented functions in Cognos I can’t guarantee that it will work for all future versions. Copying from one report to another is possible with this, but you have to initialize the report clipboard by copying something.

iFrames.zip (107 downloads)
Clipboard Editor (103 downloads)

And finally, on a personal note, I’m a sucker for free high-fives. Thanks GoTeamJosh!