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.


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.


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.


2 Responses to Two Variables You Should Have In Every Report Studio Report

  1. Michael Voyner says:

    Interesting article! I tend to use similar debugging techniques whilst developing a report, then strip out this code when the report is ready to go into production. Is there not a performance hit from having in your list columns which are not displayed (Debug = “0”), or is Cognos intelligent enough not to include these columns in the request that’s sent to the DB?

    Also, I’m curious about the “I never use boolean variables”, but I guess I’ll have to be patient…

    Keep up the good work!

    • Bob Reddert says:


      Thank you for the kind words.

      That’s a good point. You do need to consider the impact of leaving the debug items in the report when it goes into production.

      If you add columns to a query, Cognos will include them in the DB SQL regardless of whether or not they are rendered. But, as long as you are not introducing new joins or aggregation that requires new windowing to support the debug columns, the performance impact should be minimal. In most cases, I do this to include items already in the query, that I’m not displaying because I only need them for calculations.

      For additional data objects that are conditionally rendered(ex. your report has a chart and you add a conditionally rendered list table):
      – If the new object re-uses an existing query that’s already being run, there’s no database impact because Cognos will share the result set with both objects.
      – If the new conditionally rendered object uses its own query, the query will only execute if the object is rendered.

      As for booleans, I avoid using them in case I later find I’ll need to use the variable as a render variable. When using a boolean as a render variable, you can only display on true and hide on false. So, for example, if I want to display object 1 on True and object 2 on False, you cannot use a boolean. It only takes a few extra seconds to make a true/false variable a string variable, but changing a boolean variable to a string variable after you’ve already used it in 100 places could take considerable time. This is one of those situations that burned me once, and never again.

      Thanks again,

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: