Ironside Tech Tip: Standardizing Prompt Names in Report Studio

Synopsis

Define the technique behind and benefits of standardizing prompt conventions in Report Studio.

Overview

Report authors can easily create automatically generated prompt page prompts for data items in a report using the question mark syntax, as shown below:

[Branch region] = ?br?

Naming conventions for the alpha-numeric text between the question marks can be anything the Report Author specifies. Despite this fact, having various reports with differing alpha-numeric conventions for prompts can be confusing and inefficient for a variety of reasons. For example, all of the following will also successfully prompt to choose a branch region when a report is run:

[Branch region] = ?br?
[Branch region] = ?abc?
[Branch region] = ?x?
[Branch region] = ?branch?

This article describes six techniques for applying consistent naming conventions when creating prompts in reports. The first technique is the key to effectively implementing this strategy across the subsequent sections.

Technique #1: Use the word “Desired” with the Data Item NAME separated by underscore

Whenever a prompt is created, enter the word Desired between the question marks followed by the exact same spelling and case of the relevant data item name. Spaces should be replaced with the underscore character.

[Branch region] = ?Desired_Branch_region?

The reason for this naming convention is described in the following techniques.

Technique #2: The word Desired self-documents each prompt used in a report

Prompted-for values are pointing to the elements requested in a report.

The XML for the report shows Desired_ preceding all prompts:

Using a text editor and searching for Desired_ easily locates all the prompts used in the report.

Technique #3: Use of the word Desired_ with the data item name simplifies understanding what parameters need to be passed to drill-through target reports

When the Drill-Through wizard is started in a source report, it will display the parameters expected in the target report. If the parameter naming convention is not clear, an author may not be sure what data item needs to be passed to the target report.

By standardizing on the Desired_Data_Item_Name naming convention, the value that needs to be passed is clearly evident to the author of the source report. This is especially useful if another author writes the target report.

In the following example, the target list report is prompting for Product line and Year, but assumes that the other author used ?X? for time (i.e. ) and ?Y? for the product line () In this scenario, it is not clear to the author of the Target Report what value needs to be passed to satisfy the X or Y parameter:

Technique #4: Using the same naming convention combines prompts between multiple queries in the same report

A report can have one or more data containers that need to be filtered off the same prompt simultaneously. For example, the following data containers are written off of two queries. Query 1 is the list, and Query 2 is the crosstab.

In this scenario, you should use the same prompt expression for both containers, as shown below:

[Branch region] = ?Desired_Branch_region?

Because the syntax is the same in both locations, only one prompt page is returned when the report is run instead of two.

This technique will not work if the spelling or case is even slightly different between the two prompts (note capitialized “R” in region), as shown below:

[Branch region] = ?Desired_Branch_Region?

In this situation, the automatically generated prompt page will ask the user twice for the same prompt information (i.e. on two separate auto prompt pages).

By standardizing prompts to follow the Desired_Data_Item_Name naming convention (using the same spelling and case for the Data Item name), you ensure that prompts are combined between multiple queries and do not have to remember what naming convention you used for the other query.

This also applies with Unions, Joins, etc. that are all prompting for the same values from different queries. Using the same naming convention in all the queries combines them on the prompt page into the same singular prompt. (Note: in this scenario, the prompt page will also display the prompt twice, but on the same auto generated prompt page.)

Technique #5: Parameters using underscore in the name for multi-part words eliminate using a UUENCODING value in a report run as a URL

Cognos permits adding the URL for any report using the tag <A HREF= > on a web page. The URL for all reports is available under Properties in Cognos Connection.

Click the View the search path, ID and URL link to view the URL in a pop-up window

Copy the URL from the pop-up window to use it in other locations.

Below is a sample URL for a report:

The last GET Parameter is &run.prompt=true, which means that if the report has prompts, the system will prompt the user when the report is run. If true is changed to false, the URL does not prompt the executing user and instead hard codes the value(s) of the prompted-for data items into the URL. The parameters to pass are shown below in green. Each parameter is preceded by “p_” and the ampersand is standard HTML coding for each GET Parameter:

Because the variable-prompt name (e.g. Desired_Product_line_) does not contain spaces (substituted with underscore) there is no need to include the UUENCODING value of “%20” to represent a space (Note: Spaces and many other special characters such as a forward slash, a question mark, and others are not allowed in URLs with similar encoding). For this reason, using a prompt parameter name with an underscore and no spaces in the URL saves the Authors an awkward coding step.

Technique #6: Parameters used in Layout Calculations are easily identifiable

Using Technique #1 of standardized naming conventions makes it easy for report authors to choose the correct parameter specifying when to display prompt values on a report page.

Assume the following prompts are included in a report:

The report appears as follows:

Dragging a layout calculation after Selected Branch Region identifies which parameter-prompt to drag into the Expression Editor. This becomes clear due to the naming convention for each prompt:

 

 

Notes:

A secondary benefit of Technique #2 is that if the XML source code is stored in a content versioning system or file server, a simple script can loop through all report script files to determine what prompts are used in what reports. If a unique text-string like Desired_ is not used, there would not be enough uniqueness to write a regular expression to search for prompted-for data items.

Conclusions:

Standardizing naming conventions for prompts makes working with prompts in a variety of situations easier and more consistent for and among report authors creating numerous and sometimes co-related reports.