Two Variables You Should Have In Every Report Studio Report

There is an old joke that tells us that hard work pays in the long run, but that laziness pays off right now. However, in the world of software development, I think that laziness done right can pay off in the long run even better than hard work. Now there are a lot of developers who would prefer to skip the task of documenting a report they’ve developed. Sure it’s lazy, but that’s short term lazy.

I prefer long-term lazy, where I document the report now so that when I go to edit it a year later, I don’t have to spend an hour re-learning all the details of the report design. The first variable I want to talk about allows report documentation right in the report.

ShowDocumentation

Few reports are so simple that new Cognos developers can understand them intuitively. In fact, I suspect that most of your reports take even experienced developers a little time to understand. Sadly, Cognos does not give us a place to document the report, however they do give us the tools necessary to easily create one ourselves.

Report documentation can come in many forms. Maybe you have a large list of items that need to be completed (developer name, date, time, parameters, query descriptions, ,modifications, etc.), or perhaps you just have a bit of information on the design that you really need to remind yourself or another developer, the next time the report is being modified. Either way, you can put this information right in the report and use variable ShowDocumentation to hide it from the report consumers.

Create ShowDocumentation as a string variable with the expression of “0” (zero), and set the values allowed to be either 0 or 1 (I never use boolean variables, but that’s a topic for another time).

Then add text items to your report and set the render variable so that it’s only rendered if ShowDocumentation is “1” (which it never is). If you’re just trying to call out something, you can put the text item right in the report where it will be seen by every developer. You could even color it red, or make it bold, or give it a yellow background (or all of these) if you really need to get their attention. If the text is long, put it in a block with a fixed width (say 800px) and set the render variable on it. Then, any text you put inside will be word-wrapped for the developer, but still hidden to the report consumer.

If you have a lot of documentation , then you could create a report page called “Documentation“with ShowDocumentation of “1” as the render variable. Within that report page you could use tables and blocks to create a form you could fill out. Use small text variables with the render variable, placed in the actual report page (not the Documentation report page) to serve as call-outs that you could then reference in the Documentation page.

Debug

Often, while we are in the process of developing or testing a report we need information that the report consumer should not see. Perhaps it’s some information on the layout, or just numbers that are used in a calculation. To do this the lazy way, you want to be able to add this information to the report once, and be able to turn it on and off at will. That’s where variable Debug comes in.

As with ShowDocumentation, create a text variable called Debug with a hard-coded value of “0” (zero) and possible values of 0 or 1. You can then use Debug either as a render variable or a style variable to hide the items you only want the developer to see.

Then, all you need to do is change the Debug variable’s value to “1” when you are testing so that the items are visible, and then change it back to 0 when you’re ready to put the report back into production.

Here are some examples:

• In a list, you can add columns used in a calculation for validation. Use the ancestor button to navigate to the column’s List Column object and set the render variable there.
• If you are having trouble with layout, you can use the style variable to turn on an object’s border when in “debug mode”. I like to use the color fuchsia because it really stands out. Besides, how often do you see fuchsia in a report?
• Debugging a chart? Add a list using the same data source as the chart with the render variable set to Debug = 1.

Okay, you should only have to use one of these in every report (ShowDocumentation), but I find myself using Debug in a large percentage of the reports I develop.
Have you used something similar? If so, let me know.

Editing Cognos Report Studio Reports in a Text Editor

One technique for editing Report Studio reports that is too often overlooked is editing the report’s query data items in your favorite text editor (mine is Notepad ++ Portable). This is made possible because Report Studio reports are stored in XML which is fundamentally a text format.

For most of the editing you do, the Report Studio tool is the best way to do it. It keeps all the XML properly formatted and free of structural errors (report design errors are your responsibility). However, occasionally I find the need to make bulk changes, particularly in report queries, which Report Studio does not do well.

Before I proceed further, I must warn you that editing a report in a text editor is something you must do with great caution. It is very easy to introduce errors into the XML that will invalidate your report. Making backups of your reports before editing is always a good idea, but it is even more crucial to do so before performing any changes outside of the Report Studio web application.

Just to be sure I’m clear about this… BACK UP YOUR REPORT FIRST, BACK UP YOUR REPORT FIRST, BACK UP YOUR REPORT FIRST, BACK UP YOUR REPORT FIRST!

Getting the Data Items To and From Your Text Editor

There are two ways to copying a report into a text editor and back out. You can do the whole report, which works in all browsers supported by Report Studio, or you can do specific items in a report, which currently only works with Microsoft IE (internet Explorer).

Whole Report

The XML for an entire report can be quite large and if you are not familiar with XML, it can seem very complicated. This can make it quite difficult to locate the specific data items you want to edit. For this reason, I avoid working with the whole report, but if you don’t have IE (working on a Mac for example), this may be your only option.

For the whole report, there are two menu items you can use:

• Tools -> Copy Report to Clipboard
  This will copy the full XML of the report into the operating system clipboard. Then you just need to paste it into your text editor.
• Tools -> Open Report from Clipboard
  From your text editor, select the entire report contents and copy it, then use this option in Report Studio to open the modified report from the clipboard.

One of the risks of using this method is that when you save the report, if you save over an existing copy of the report, you will re-create the report with a new internal report id. This could cause you a big problem if you have drill-throughs to that report, because it will break those links. To work around this problem, save your report to a temporary folder and then in Cognos Connection, copy the report and paste it into the original folder. This will overwrite the report but retain the original report id.

Specific Query Data Items

For specific data items, make sure you open the report in an IE browser and confirm that Report Studio is using the operating system clipboard (in Tools -> Options -> Advanced (tab)). Then, simply cut (ctrl-x) the query items from Report Studio and paste them into your text editor. When you are done editing, you copy the text from your text editor and paste them back into your report query. You may also need to reposition the items in the Report Studio Query Explorer after you have pasted them.

Editing the Query Data Items

From here on, we’ll be discussing editing specific data items. The techniques are the same if you are working with the whole report, but as said before, the XML is much larger and too complex, to use as an example.

Here is an example of the XML from a pair of data items. The XML has been reformatted (addition of line feeds and indentation) and highlighting added for readability.

<RSClipboardFragment version="2.0"> <dataItem name="Base URL"> <expression>[versionConstants].[Base URL]</expression> </dataItem> <dataItem name="Base Gateway"> <expression>[versionConstants].[Base Gateway]</expression> </dataItem> </RSClipboardFragment>

The highlighted portion (green and yellow) show the XML, which you should not change unless you are familiar with both XML and the XML schema that Cognos uses.

Between each of the expression opening and closing tags (<expression> and </expression> respectively) are the data item expressions that you would find in Report Studio by double clicking on the data items in a query. These are the areas that to which we want to limit our editing.

Let’s say I needed to change the sub-query of these two items from “versionConstants” to “chapterConstants”. In my text editor, I could do a search and replace, searching for “[versionConstants]” and replacing it with “[chapterConstants]”. Please note that it is important to provide sufficient context to the search term so that you don’t accidentally make changes you didn’t intend. For example, if I had just searched for the word “version”, it would have also modified the first line of the XML and made it invalid, so I wouldn’t be able to paste it back into my report.

Of course, this wouldn’t be worth the effort if I were just making this change to 2 data items, but what if I were changing 20 data items, or 100? That is when this technique becomes practical.

Summary

It’s also worth noting that editing in a text editor can work with more than just query data items. In fact it works with just about any object type in Report Studio (variables, pages, text items, lists, images, etc.), but most other items are more complicated to change and require an understanding of XML, HTML, and the Cognos XML schema.

This technique requires a bit of practice, but once you’ve mastered it, you’ll be bulk-editing Cognos reports like a ninja.

Finally – RAVE Visualizations

I’m finally diving into the customization of RAVE Visualizations in Cognos 10. I don’t expect to have anything truly insightful in the near future, but if you’re wanting to get started, this article provides an excellent overview of the fundamentals.