Advanced Prompting Ibm Cognosbi83 84

Tip or Technique
IBM Cognos Forum 2008

Session 1259 Advanced
Prompting
Product(s): IBM Cognos 8 BI
Area of Interest: Reporting
Session 1259 Advanced Prompting 2
Copyright
Copyright © 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC
is an IBM Company. While every attempt has been made to ensure that the
information in this document is accurate and complete, some typographical
errors or technical inaccuracies may exist. Cognos does not accept
responsibility for any kind of loss resulting from the use of information
contained in this document. This document shows the publication date. The
information contained in this document is subject to change without notice.
Any improvements or changes to the information contained in this document
will be documented in subsequent editions. This document contains
proprietary information of Cognos. All rights are reserved. No part of this
document may be copied, photocopied, reproduced, stored in a retrieval
system, transmitted in any form or by any means, or translated into another
language without the prior written consent of Cognos. Cognos and the
Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated)
in the United States and/or other countries. IBM and the IBM logo are
trademarks of International Business Machines Corporation in the United
States, or other countries, or both. All other names are trademarks or
registered trademarks of their respective companies. Information about
Cognos products can be found at www.cognos.com
This document is maintained by the Best Practices, Product and Technology
team. You can send comments, suggestions, and additions to BestPractices-
ProductandTechnology@cognos.com.
IBM Cognos Proprietary Information

Contents
1 INTRODUCTION ............................................................................................ 4
2 ENHANCEMENTS TO PROMPT CACHING....................................................... 5
2.1 DYNAMIC PROMPT CACHE REFRESH.............................................................................. 5
2.2 MULTILINGUAL CACHE .............................................................................................. 6
2.3 UNILINGUAL CACHE ................................................................................................. 8
3 REUSABLE TOOLBOX OBJECTS ..................................................................... 9
3.1 WORKSHOP: RE-USABLE HTML ITEM......................................................................... 12
3.2 WORKSHOP: REUSABLE PROMPT CONTROLS ................................................................. 18
4 CUSTOM PROMPT CONTROLS OVERVIEW .................................................. 23
4.1 CREATE THE CUSTOM PROMPT CONTROL ..................................................................... 24
4.1.1 Beer Glass Control............................................................................................. 24
4.2 PLACE THE CUSTOM PROMPT INTO THE PROMPT PAGE ..................................................... 25
4.3 SET THE PARAMETER VALUES ................................................................................... 26
5 WORKING WITH THE SAMPLES .................................................................. 27
5.1 SETTING UP THE SAMPLES ....................................................................................... 27
5.2 CUSTOM PROMPT BUTTONS ..................................................................................... 28
5.3 BEER GLASS ........................................................................................................ 32
5.4 DYNAMIC PICKLIST PROMPT ..................................................................................... 36
5.4.1 How does the Dynamic Picklist Prompt Work ....................................................... 39
5.5 TAB CONTROL PROMPT........................................................................................... 41
6 CONCLUSION .............................................................................................. 46

1 Introduction
In this paper we will cover two topics: changes to prompting in IBM Cognos
8.4 and custom prompt controls.
The changes to prompting in the IBM Cognos 8.4 release are designed to
both extend the prompt cache feature and make the prompt cache easier to
administer.
The custom prompt controls are designed to teach you the principles of
creating your own prompt controls and provide some useful example such as
a tabbed prompt interface and an on demand pick list.
The custom prompt controls have been tested with both IBM Cognos 8.3 and
IBM Cognos 8.4.
This paper was presented at the 2008 North America IBM Cognos Forum.

2 Enhancements to Prompt Caching

IBM Cognos 8.4 adds two additional features to the existing prompt caching
feature. The first makes administration of the caches much easier, the second
provides enhanced multi-lingual user support.
2.1 Dynamic Prompt Cache Refresh

IBM Cognos 8.3 introduced prompt caching which allows the prompt query
values to be cached and reused. The cache refresh was controlled through
the use of Jobs to run the report prompt queries to refresh the cache.
Customer feedback indicated that while this feature went along way to
providing better prompt performance by reusing query results, the use of
jobs to administer the prompt cache refresh was an onerous task which
increased the maintenance work required of an administrator.
Therefore, the management of the prompt cache has been simplified for IBM
Cognos 8.4. For upgrade compatibility, Jobs can still be used to maintain the
prompt cache. However, a new option has now been added to the report
properties Report Tab as so:
When this option is used, the prompt cache will be managed automatically by
the system with no requirement for Jobs or other intervention.
This option uses user report execution to drive the prompt cache refresh
activity. When the report is executed, we determine if the cache is valid or
expired based on the expiry period specified in the report properties. If the
cache is fresh then no action is taken. If the cache is expired then the cached
data is deleted and the prompt query is executed to create the new cache.

2.2 Multilingual Cache 1

The prompt cache is multilingual and the query used to populate the cache is
driven by the users Content Locale 2 (the language used to run reports and
view data).
When the cache is refreshed using the dynamic refresh method, the content
language of the current user is used to run the prompt query. Only when
subsequent users with a different content language run the report will the
cache for another language be created. When the prompt cache is expired, all
languages are deleted at the same time.
To see this in action consider the following scenario and events:
A report is newly created with no prompt cache. The Dynamic Prompt

Cache option is set with an expiry of 7 days.
On the day the report is created, a French language user runs the
report causing the French language prompt cache to be created. This
sets the cache creation date.
On day 2, two more French language users run the same report. As
the French language prompt cache already exists, it is used for all
users.
On day 3, a German language user runs the report. As there is no

German prompt cache, the prompt query is run and the German
prompt cache is created. The French cache is not affected by this
operation. On day 3, new French language users also run the report
and use the French language cache created on day 1.
On days 4 through 7, additional French and German users run the

report, using their respective language prompt caches.
On day 8, a German user runs the report. Since the expiration date
was set by the French cache on day 1, the prompt cache is now older
than the 7 day threshold. The prompt cache is deleted in all
languages even though the German cache is only 4 days old. To
satisfy the German report request, a new German language cache is
now created.
1
Note that with the IBM Cognos 8.3 job based cache refresh, the prompt cache was created
in all languages when the job was run.
2
Locale is a combination of language and region. For example EN-US is English language in
the United States region. While it is possible to differentiate data by locale – “Tire” in North
America versus “Tyre” in the UK, most companies do not make such a differentiation and
instead use only the language to differentiate data. The sample databases that come with
IBM Cognos 8 are perfect examples of this approach.

No other users run the report for 6 months. The cache is unaffected
as there is no user operation to drive the refresh.
An English language user runs the report. The cache (German) is past
the expiration date so it is cleared and an English cache created.
And so on, with language specific data being cached as required.

2.3 Unilingual Cache

An interesting variation on multilingual applications has a multilingual users
reporting against a unilingual database. That is, the users wish to see the
data presented according to their content locale – numbers and date in local
format such as $123.45 versus 123,45$ or 1 January 2008 versus janvier 01,
2008 for example – but the data is all in a single language. One IBM Cognos
customer, a major airline, records all information in English but allows users
to choose their language for IBM Cognos 8 user interface and data
formatting.
In this variation, there is no value in creating prompt caches for different user
content languages as they would all contain the same data from the
unilingual database.
To meet this need, IBM Cognos 8.4 includes an advanced server property
which allows you to specify the single language for which all prompt caches
are created. The property RSVP.PROMPTCACHE.LOCALE=<locale> is set in
the server administration screens in Cognos Connection and tells the server
which language is to be used for all prompt caches. This will take precedence
over the user content locale when the prompt cache is created.
As it is difficult to demonstrate the advanced server property in action, a

workshop scenario will not be presented on this topic. For additional
information on advanced server properties, please see the IBM Cognos 8.4
administration manual.

3 Reusable Toolbox Objects 3

Many times reporting projects require the same Report Studio objects, such
as a prompt definition, in different reports. This can be done either by using
report layout references between reports or by using custom toolbox items.
As the prompt techniques used later in this document use custom toolbox
items this section will focus on this approach instead of layout component
references, which are covered in the Report Studio User Guide.
A custom toolbox item is simply a snippet of valid xml from a report 4 . For
example, the HTML item in the standard Report Studio toolbox is the
following xml report specification snippet:

<HTMLItem id="HTMLItem">
<dataSource>
<staticValue/>
</dataSource>
</HTMLItem>
Before custom toolbox entries can be created you should have, at least, a
basic understanding of the Report Studio XML report specification. The IBM
Cognos 8 BI SDK guide fully documents and explains the report specification
xml schema.
Based on the report specification, custom HTML/JavaScript code to be added

to the report appears in the <staticValue> tag of the HTMLItem element as
so:
<HTMLItem>
<dataSource>
<staticValue>This is my <b>CUSTOM</b> HTML.</staticValue>
</dataSource>
</HTMLItem>
This example would display simple text in the report in HTML format as so:
To add this to the Report Studio toolbox, you need to be aware of two files 5 :
1. Toolbox.xml
2. ToolboxControls.xml
3
This topic has been well covered previously in documentation and proven practices papers if
you feel the need for more information.
4
Report Studio toolbox items are not all simple xml report specification snippets but the
snippet mechanism is documented and supported and meets our needs.
5
These files are located in the ..\c8\webcontent\pat\res directory.

Toolbox.xml creates the structure of the toolbox determining which items

show up in which Report Studio context; as you navigate to different parts of
the Report Studio user interface, different objects will appear in the toolbox.
The item name, context, parameters and so on are defined in the
Toolbox.xml file.
In toolbox.xml, the HTML item definition for example appears as so:

Definition Meaning
<listItem This item appears in a list of items
controlRef="HTMLItem" The id of the item as it appears in

ToolboxControls.xml (HTMLItem). This id
must be unique in this file.
value="" Reserved for Report Studio use. When
creating new entries, always use the same
value that has been used for a default item.
label="HTML Item" The label which appears in the Report Studio
toolbox 6 .
tooltip="HTML Item" The tool tip which appears in the Report
Studio toolbox.
smallIcon="HTMLItem.gif"/> The name of the icon to appear in the
toolbox. The icons can be found in the
directory: …\c8\webcontent\pat\images
ToolboxControls.xml defines the xml report snippets. Remember that the

name used in the toolbox.xml controlRef tag and the toolboxControls.xml id
must be the same and that the xml snippet must be valid xml.
6
You will see idsLabel= and idsTooltip used by Report Studio. These are references to a
localized message file if you wish to support Report Studio users in multiple languages.

ToolboxControls.xml defines the item itself as so:

Definition Meaning
<HTMLItem id="HTMLItem"> The HTMLItem element tells Report Studio
what type of object this is 7 .
The id=”HTMLItem” property links the

element back to Toolbox.xml to ensure the
correct placement of the object in the
Report Studio toolbox. This id must be
unique in this file.
<dataSource> The definition of the item as specified in the
<staticValue/>
XML report specification schema.
</dataSource>
</HTMLItem> Ends the definition
Remember that the XML snippet must be valid within a report specification.
How do you know? Test it before you create the custom toolbox entry.
Once the custom toolbox entry has been created, it appears in Report Studio
and can be dropped into the report.
7
Remember that the report specification XML schema defines the object types available in a
report. You must reference a valid report object type.

3.1 Workshop: Re-Usable HTML Item

This workshop will demonstrate how to create an HTML item for use in
Report Studio.
Open Report Studio with the GO Sales (query) package 8 .
Create a list report with

• \Sales (query)\Products\Product line
As so:
Drop an HTML Item from the Report Studio toolbox into the page body after
the list:
Double click the HTML item to edit the HTML content as so:
8
This package is provide with the IBM Cognos 8.4 samples. A system administrator can assist
with deploying the sample content if required.

Click OK and run the report:
This shows that the HTML item is working and well formed.
Return to Report Studio and select the HTML item. Copy the HTML item to
the Windows clipboard using CTRL-c or the copy button from the Report
Studio toolbar.
Open notepad or another text editor and paste the contents of the clipboard
into the text editor to see the XML code:
<RSClipboardFragment version="2.0">
<HTMLItem>
<dataSource>
<staticValue>This is <b>MY</b> HTML item.</staticValue>
</dataSource>
</HTMLItem>
</RSClipboardFragment>
Line breaks have been added to make the xml snippet more legible.
Delete the opening and closing tags of the RSCliboardFragment element (the
first and last lines of the above sample):
<HTMLItem>
<dataSource>
</dataSource>
</HTMLItem>
The staticValue content contains somewhat cryptic information such as

<b;&gt. This is HTML encoded text to ensure that special characters such
as < and > (&lt and &gt) are transmitted correctly. The toolbox objects do
not required HTML encoding of special characters so the encoded characters
could be replaced with regular characters. However, leaving them as encoded
characters will not impact the toolbox object definition.

Open Toolbox.xml.
Insert a new line as in the highlighted text below:


<resources>

<listView id="Toolbox_PageView" classPrefix="clsListItem_tb">
<listItems>
<listItem controlRef="myHTMLItem" value="A" label="My HTML Item"
tooltip="This is my personal HTML Item"/>
Note that the order of the entries in this file determines their order in Report
Studio so the new item will appear first in the Toolbox.
Save and close the Toolbox.xml file.
Open ToolboxControls.xml.
Copy and paste the new HTML item definition into this file:

<resources>
<xmlFragment id="ToolboxControls">

<HTMLItem>
<dataSource>
</dataSource>
</HTMLItem>

Note that a comment tag has been added before the new HTML item. These
comments are not strictly required by help to locate and document content if
you are making changes to the ToolboxControls.xml file.
Add the ID to create the link back to Toolbox.xml:


<resources>

<HTMLItem id="myHTMLItem" >
<dataSource>
</dataSource>
</HTMLItem>
Save and close this file.
The process to add the new item is now complete. To see the new item in
Report Studio simply close and re-open Report Studio to apply the changes.
The toolbox.xml and toolboxCongrols.xml are loaded when Report Studio
starts, hence the requirement to re-open Report Studio. However, there is no
need to restart the IBM Cognos 8 server to apply the changes.
Create a new list report using Product line:

Open the Toolbox and note that our custom item appears first:
Drop the HTML item into the report after the list:
From this point forward, everything is just as if the HTML item had been
created from scratch. You can make changes to the new HTML item in your
report layout as you would with any other HTML item.
Run the report:

Adding elements to the toolbox review:

1. Create the object you need in Report Studio.
2. Copy the item to the clipboard
3. Delete the first and last lines with the RSClipboardFragment
references.
4. Create a new entry in Toolbox.xml using a unique id name
5. Create the new entry in ToolboxControls.xml
a. Paste the report XML in
b. Add an id
6. Use it in your report.
Keep in mind that once the new object has been inserted into your report it
exists independent of the object defined in the toolbox. This means that
changes to the toolbox definition will not be applied objects that have already
been inserted into the report.

3.2 Workshop: Reusable Prompt Controls

There may be times when a report author wishes to make the re-use of a
given prompt control definition very easy. For example, suppose the author
has created a picklist prompt with a long series of static values. Setting this
up in Report Studio each time involves:
1. Drag and drop a value prompt into the report
2. Set the Select UI property to List box
3. Set the Multi-select property to Yes
4. Enter the static values
For short lists this process is fairly simple but for long lists of static values,
recreating the prompt each time can become tedious very quickly.
This workshop will demonstrate how to create a reusable prompt so that an

author does not need to enter the values for each new report.
Open Report Studio with the GO Sales (query) package.
Create a list report with:

• \Sales (query)\Order method\Order method:
Select Order method and press the Build Prompt Page toolbar button.
Report Studio will create an appropriate Order method filter, insert a prompt
page, and create the prompt with a query to populate it.
Assuming that the list of order methods does not change it is possible to use
a list of static values rather than a query to populate the prompt control.
Select the prompt.
Set the Query method to (Default).

Add static values for:
Run the report and test the various static values to make sure that they
match the requirements of the query filter expression.
Return to Report Studio.
Select the prompt and copy it to the Windows clipboard.

Open notepad and paste the code in. Delete the RSClipboardFragment tags
and you will have a standard prompt definition:
<selectValue parameter="Order method" required="true"
multiSelect="true" range="false" autoSubmit="false"
selectValueUI="listBox">
<XMLAttributes>
<XMLAttribute name="dataType" value="xsdString" render="true"/>
</XMLAttributes>
<selectOptions>
<selectOption useValue="E-mail">
<displayValue>E-mail</displayValue>
</selectOption>
<selectOption useValue="Fax">
<displayValue>Fax</displayValue>
</selectOption>
<selectOption useValue="Mail">
<displayValue>Mail</displayValue>
</selectOption>
<selectOption useValue="Sales Visit">
<displayValue>Sales Visit</displayValue>
</selectOption>
<selectOption UseValue="Special">
<displayValue>Special</displayValue>
</selectOption>
<selectOption UseValue="Telephone">
<displayValue>Telephone</displayValue>
</selectOption>
<selectOption useValue="Web">
<displayValue>Web</displayValue>
</selectOption>
</selectOptions>
</selectValue>
We will name our prompt OrderMethodPrompt.

Open Toolbox.xml.
Create a new line:

<listItem controlRef="OrderMethodPrompt" value="C" label="Order method
prompt" tooltip="Order method prompt with statis values"/>
Note that the value property is “C”. This is obtained from the default
properties of a selectValue prompt object as listed in the Toolbox.xml file.
The selectValue object is the basis for the custom value prompt control that
was created in Report Studio.
Save the Toolbox.xml file.
Open ToolboxControls.xml and paste the prompt definition in within the

<xmlFragment id="ToolboxControls"> element.
Add the id=”OrderMethodPrompt” attribute.

<selectValue id=”OrderMethodPrompt” parameter="Order method"
required="true" multiSelect="true" range="false" autoSubmit="false"
selectValueUI="listBox">
…
</selectValue>
Save this file.
Close and re-open Report Studio.
Create a list report with:

• \Sales (query)\Order method\Order method:
Create a filter on Order method (note that you must use the same parameter
name as specified in the re-useable prompt control in the parameter="Order
method" attribute from the ToolboxControls.xml file):
[Order method] in (?Order method?)
Add a new prompt page.

Drag the new Order Method Prompt from the Toolbox into the layout of the
new prompt page.
Run the report.
The report is now complete and is using the pre-defined object from the
custom Toolbox definition.
While this type of modification is not something that a report author would
usually require, it will be used as a basis for setting up the content in the next
section.

4 Custom Prompt Controls Overview

This section discusses the basic functionality behind custom prompt controls
followed by some specific prompting examples. The goal is to provide report
authors with information on creating custom prompt controls and on using
the provided samples.
Custom prompt controls can be used when the supplied prompt controls do
not meet the reporting requirements. Custom prompt controls can be defined
using HTML/JavaScript code embedded in a report prompt page or query
page layout to create the desired user experience and supply values to the
report expressions. The easy part is supplying values to report expressions.
There are three steps required to add a custom prompt to a report:

1. Create the custom prompt control
2. Place the custom prompt control into the prompt page 9
3. Set the parameter values
9
Or into a report page as appropriate

4.1 Create the Custom Prompt Control

The toughest part of this entire venture is designing and programming a
custom prompt control to meet the reporting needs. This portion of creating a
prompt control requires HTML/JavaScript programming skills which are not
covered within this document but are available through many 3rd party
instruction manuals, courses, and online references.
4.1.1 Beer Glass Control

The following is an example of a custom prompt control. At run time it
appears as so:
This prompt control is obviously far different from anything IBM Cognos
supplies in Report Studio. The user can use the buttons to select a higher or
lower value using the Drink and Fill buttons.

4.2 Place the Custom Prompt into the Prompt Page

This is very easily done. Report Studio provides an HTML object in the
Toolbox for just this sort of purpose.
The HTML object can contain any HTML/JavaScript code you specify. The
code is placed into the prompt page to allow the browser to execute it.
If a custom prompt control will be used more than once, it would be worth
while to add it into the Report Studio Toolbox as discussed in section 3 and 4.
There are some things that should be considered when creating a re-useable
custom prompt toolbox items:
1. All prompts must have a unique name – this is accomplished in the
JavaScript using an HTML div. The unique name is specified by the
report author as discussed in the workshop below.
2. Prompts set parameters – you need a way to pass the parameter
name to the custom prompt control
3. The prompt may have additional parameters to set. For example, the
Beer Glass prompt allows the Report Studio author to set the high and
low values.
Prompts are uniquely identified by placing them into a named HTML div.

4.3 Set the Parameter Values

Prompt values are passed to the report as parameters. Parameters are
specified in Report Studio filters or calculations using the ?<parameter
name>? syntax such as [Country] in ?CountryParm?.
In a prompt page, when the Finish button is pressed, parameters are passed
to the IBM Cognos 8 BI server as HTML form field variables. In order for the
IBM Cognos 8 BI server to differentiate parameter variables from other
variables, parameters use the naming convention p_<Parameter name>.
Therefore, the parameter CountryName would be passed in the form field
variable p_CountryName.
This makes it very easy for a custom prompt control to pass a value to the
parameter by simply setting a form field variable with the correct name.
The prompt control must set the form field variable with the appropriate
name to the value specified by the user.

5 Working with the Samples

5.1 Setting Up the Samples
1. Unzip the files into a new directory
2. The bmp and png images are used during report execution. Copy the
bmp and png files to the webcontent\samples\images directory.
3. The gif files are used to create the icons in the Report Studio toolbox.
Copy the gif files to the webcontect\pat\images directory
4. Insert the contents of toolbox.xml into the Toolbox.xml file located at
../c8/webcontent/pat/res. The items should be inserted in the
Toolbox_PageView section, immediately after the following lines:
<listView id="Toolbox_PageView" classPrefix="clsListItem_tb">
<listItems>
5. Insert the contents of toolboxControls.xml into the toolboxControls file

located in the ../c8/webcontent/pat/res directory. The entries should
be added immediately after the folloing lines:
<resources>
6. Merge reportstudio_en.xml into the same-named file in

webcontent/pat/res into the RSB UI section after the line that reads:
<section name="RSB" type="UI">
7. Copy the customPromptControls.js file to webcontent\prompting
The custom controls are coded in the customPromptControls.js file. The

HTML/JavaScript found in toolboxControls.xml is the minimum required to
expose the prompt controls in Report Studio.
Using an external reference to the Javascript code using the

customPromptControls.js allows the code to be updated and propagate the
changes to all reports. While it is possible to define the Javascript code within
the ToolboxControls.xml file, doing so will result in static Javascript code
embedded in each report specification. Updating the code embedded in a
report will require a report author to make changes to each of the reports
individually.

5.2 Custom Prompt Buttons

The custom prompt buttons are really just default prompt buttons with
images used in place of text. The following steps will illustrate how to use
these new items.
Create a new list report with:

• \Sales (query)\Product\Product line
Select Product line and press the Build Prompt Page toolbar button.
A prompt page is created with the default prompt buttons:
Select and delete each of the prompt buttons.
Drop a Prompt Button Set into the page footer.

Run the report:
A much nicer set of prompt buttons appears.
The Prompt Button Set is actually a standard report Block object with 4
prompt buttons in it. The <contents> of each prompt button have been
customized with a table, an image, and some text. Here is a standard Cancel
button specification:
<promptButton type="cancel">
<contents/>
<style>
<defaultStyles>
<defaultStyle refStyle="bp"/>
</defaultStyles>
</style>
</promptButton>

Here is the custom Cancel button:

<promptButton type="cancel">
<contents>
<table>
<style>
<defaultStyles>
<defaultStyle refStyle="tb"/>
</defaultStyles>
<CSS value="border-collapse:collapse;width:100%"/>
</style>
<tableRows>
<tableRow>
<tableCells>
<tableCell>
<contents>
<image>
<dataSource>
<staticValue>../samples/images/cancel.bmp
</staticValue>
</dataSource>
</image>
</contents>
</tableCell>
<tableCell>
<contents>
<textItem>
<dataSource>
<staticValue>Cancel</staticValue>
</dataSource>
</textItem>
</contents>
</tableCell>
</tableCells>
</tableRow>
</tableRows>
</table>
</contents>
<style>
<defaultStyles>
<defaultStyle refStyle="bp"/>
</defaultStyles>
</style>
</promptButton>

The definition for each of the buttons is part of the standard XML report
specification, not custom HTML or JavaScript. The contents of each button
are simply defined with a single-row table with two cells. One cell contains
and image and the other cell contains the text “Cancel”. IBM Cognos 8 knows
how a prompt button behaves, for example when it is enabled and disabled,
so there is no need to do any custom programming for the button actions. At
run time, the prompt buttons are just another part of the report to be
executed using standard IBM Cognos 8 functionality.

5.3 Beer Glass

The beer glass control is a custom HTML/JavaScript control that allows a user
to select a parameter value by emptying or filling a visual beer glass. The
following steps will walk through the process of creating a report using this
custom prompt control.
Open Report Studio with the GO Sales (query) model.
Create a new list report

• \Sales (query)\Order\Order number
• \Sales (query)\Sales\Quantity
Sort ascending on Quantity
Run the report.
Page down and notice that the Quantity values start at 1 and go to much
higher values.
Return to Report Studio.
Create a filter [Quantity] >= ?pQty?
Note that the name of the parameter is pQty.
Add a prompt page to the report.
Drop the Beer Glass Prompt into the new prompt page.
You will see an HTML item in your report as so:
Remember that the custom prompt control is written in HTML/JavaScript that

is executed by the browser when you run the report.
Double click the HTML item to see the HTML source code.
This code for the prompt control is not actually in the beer glass prompt
toolbox object. Rather, it calls functions in the customPromptsControls.js file
to create the prompt.

Access the HTML definition of the HTML item representing the custom prompt
control. The individual elements of the prompt control are:
Definition Meaning
'<script Tells the browser which file
src="../prompting/customPromptControls.js the prompt control is in.
"></script>' +
Do not change this.
'<div id="[BeerGlassContainer1]"></div>' The HTML div provides a
+ unique id for referencing the
prompt control. Change this
only if there are more than
one beer glass prompts on
the same prompt page so
that each control has a
unique name.
'<script>beerGlassControl ( The name of the function
which creates the prompt.
Do not change this.
"[BeerGlassContainer1]", Must match unique id
assigned to the div element.
"[BeerGlassParameter1]", The parameter name you
used in the report filter of
expression.
The default parameter used by the beer glass prompt is

[BeerGlassParameter1] 10 . As we used the parameter pQty in our filter,
change this to “pQty”.
Note that the parameter name is case sensitive and must be in double
quotes; pQTY will not work.
10
The [ ] are part of the parameter name.

Run the report:
Place the mouse cursor over the Drink or Fill button to change the value to
85. Press the Finish button and notice that the Quantity values have been
filtered such that only values greater than 85 show up in the report output.
The report is now complete and the custom prompt allows the report author
to tailor the report to needs the business and the consumer.
The beer glass prompt JavaScript does some interesting things in terms of
emptying and filling the glass. From a prompt perspective the most
interesting thing it does is to change the value of the form field variable
called p_pQty. Within the JavaScript code, one of the first lines takes the
supplied variable name and prepends p_ to it:
var sFullParameterName = 'p_' + sParameterName;
When you change the prompt value with the Drink and Fill buttons, the value
of this p_pQty form field variable is set. This form variable is passed to the
report once the prompt page is submitted using the Finish button.

The remainder of the Javascript simply defines the look and feel of the beer
glass image as the drink and fill functions are applied to change the numeric
value associated with the prompt control.

5.4 Dynamic Picklist Prompt

This custom prompt control appears to be a normal picklist but it has one
large difference – it is only populated when the user clicks on the control
itself. This allows the prompt page to be displayed very quickly as the prompt
query and associated processing are do not need to be processed before
rendering the prompt page. This is ideal for prompts which are rarely used.

• \Sales (query)\Product\Product number
• \Sales (query)\Product\Product name
Sort ascending on Product number:
Create a new filter with Product number: [Product number] >= ?ProdNum?
Note that the name of our parameter is ProdNum.
Add a prompt page.
Drop a Dynamic Picklist Prompt into the prompt page.
The HTML item used to define the custom dynamic picklist control shows up
in the report as so:
Remember that the custom prompt control is written in HTML/JavaScript

which is processed by the client web browser when the report is executed.
Double click the HTML item to see the HTML source code.
This code is not actually the prompt. Rather, it calls functions in the
customPromptsControls.js file to create the prompt.
Definition Meaning

src="../prompting/customPromptControls.js the prompt control is in.

"></script>' +
Do not change this.
'<div id="[PicklistContainer1]"></div>' + The HTML div provides a
unique name. Change this
only if you have more than
one dynamic picklist prompts
on the same prompt page so
that each has a unique id.
'<script>dynamicPickListControl ("' + The name of the function
ModelPath() + '", which creates the prompt.
Do not change this.
"[PicklistContainer1]", Must match unique id
defined by for the div
element.
"[PicklistParameter1]", The parameter name you
used in the report filter of
expression.
"[Label]", The text label to display
when an actual picklist value
is not selected.
"[UseValue]", The model path of the
required Use value data item
"[DisplayValue (optional)]" The model path of the
optional Display value data
item.
);</script>'
Change the parameter name to “ProdNum”.
Change the label to “Product name”.
To set the UseValue and DisplayValue the model path of the Product number
and Product name data items must be determined.

In the Report Studio data tree (left pane model tree), locate the Product
query subject:
Right click on Product number and select Properties.
Copy the Ref value to the Windows clipboard.
Close the property sheet.

Double click the HTML item and replace the "[UseValue]" with the Ref value:
"[Sales (query)].[Product].[Product number]"
Repeat this process to determine the model path for the Product name and
use this path for the Display value:
Run the report.
The prompt is displayed with the Label value:
At this time, the prompt is not populated. Nor has the prompt query been
executed.
Click the down arrow. The prompt is populated, the list expands and the
report user can choose a value for the prompt control. You may have to scroll
down to find the prompt buttons.
5.4.1 How does the Dynamic Picklist Prompt Work

This is the most complex example included. The code to fetch the prompt
values dynamically is very clever.
When you click, the Dynamic Prompt Control JavaScript does the following:
1. Obtain the paths for the Use and Display data items
2. Create a simple XML report specification with a prompt page, a
prompt and a query with the Use and Display items
3. Runs the report specification with a return value of the prompt page
as HTML fragment
a. In other words, a JavaScript variable now contains the HTML
for a prompt page.
4. Locate the prompt control in the HTML by identifying the data
between the <selectOptions> and </selectOptions> tags
5. Strip out extraneous characters and convert the HTML elements into
the values for the custom prompt control.
6. Insert these values into the dropdown list

The browser then displays the prompt, the user selects a value, and the
p_ProdNum form field variable is set.

5.5 Tab Control Prompt

The Tab Control Prompt allows a report author to create a tabbed prompt
interface. This is ideal when there are prompts which used infrequently and
can be removed from the primary prompt interface. The tabbed interface
hides the prompts from view but keeps them within easy reach of the report
consumer. The prompts which appear on the second and subsequent tabs
are not processed until the user selects the tab. By delaying the execution of
the prompt queries there is a reduction in the resources required to produce
the prompt page so performance can be improved.
The tab control operates using a conditional block driven by the tab selection.
The following steps will create a report to illustrate the tabbed prompt
interface.

• \Sales (query)\Product\Product line
• \Sales (query)\Order method\Order method
• \Sales (query)\Sales\Quantity
As so:
Create two filters as so:

Note that the Order method name filter is optional.
Create a prompt page.
Drop the Tab Control Prompt onto the prompt page.
Edit the HTML:

Definition Meaning
src="../prompting/customPromptControls.js" the prompt control is in.
></script>' +
Do not change this.
'<div id="[tabContainer1]"></div>' + The HTML div provides a
unique id for referencing
the prompt control.
Change this only if you
have more than one
custom prompt on the
same prompt page so that
each control has a unique
id.
"<script>tabControl ( The name of the function
which creates the prompt.
Do not change this.
'[tabContainer1]', Must match unique id
defined by the div element.
'[tabParameter1]', The parameter name you
used in expression of the
variable tied to the prompt
page conditional block.
['[Tab1]', '[Tab2]', '[Tab3]'], A JavaScript array of tab
names. Change the tab
names as required. You
can specify any number of
tab names separated by
commas.
'" + (IF (ParamCount('[tabParameter1]') = Tells the function how
0) THEN ('0') ELSE (ParamDisplayValue many tabs are defined in
('[tabParameter1]'))) + the array. Do not change
this.
"');</script>" Ends the script. Do not
change this.

Set the Tab names to Product line and Order method:

'<script src="../prompting/customPromptControls.js"></script>' +
'<div id="[tabContainer1]"></div>' +
"<script>tabControl ( '[tabContainer1]',
'[tabParameter1]',
['Product line', 'Order method'],
'" + (IF (ParamCount('[tabParameter1]') = 0) THEN ('0') ELSE
(ParamDisplayValue ('[tabParameter1]'))) +
"');</script>"
Be sure not to delete the [ ] around the tab names as these denote a
JavaScript array.
The tabs have now been created. When a user clicks a tab, the value of the
parameter called [tabParameter1] is set.
The next step is to create a variable using the tab parameter and tie the
conditional block to this parameter.
In Report Studio, open the Condition Explorer:
Create a new String Variable with the name SelectedTab and the expression:
ParamValue('[tabParameter1]')
This ties the variable to the parameter used by the tabbed prompt controls
for switching tabs. When a user clicks on a tab this will set the tab parameter
value, the variable will then update, and the conditional block will change to
reflect the new tab parameter value.

Add the value 1 to the Values list as so:
This really defines two variable values: 1 and Other. Additional tabs can be
defined by adding the tab numbers as sequential values in the Values list of
the variable.
Go to the prompt page.
Select the conditional block and set the Block Variable property to
SelectedTab.
Set the Current Block property to Other.
Drop a Value prompt into the Conditional Block.
When the Wizard starts, set the parameter to use the existing ProdLine
parameter.
Click Next.
Click Finish (take the default query settings).
Set the Current Block property to 1.
Drop a Value prompt into the Conditional Block.
When the Wizard starts, set the parameter to OrderMethod.
Click Next.
Click Finish (take the default query settings).

Run the report:
The user can click “Product line” or “Order method” to switch tabs.
The Order method prompt is not processed (including running the prompt
query) unless the user change tabs. This can both conserve resources and
enhance performance.
The Tab Header Control Prompt object that was added to the custom toolbox
objects works in the same way but the report author must create the
conditional block from scratch rather than using the one defined by the Tab
Control Prompt toolbox object.

6 Conclusion
The Report Studio interface can be updated with custom toolbox objects to
simplify report creation and facilitate the distribution of custom prompt
controls. These custom prompt controls expand the capabilities of IBM
Cognos 8.4 to satisfy a much larger range of business prompting
requirements and enhance the end user reporting experience.

Advanced Prompting Ibm Cognosbi83 84

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Advanced Prompting Ibm Cognosbi83 84

Transféré par

Droits d'auteur :

Formats disponibles

Tip or Technique

IBM Cognos Forum 2008

IBM Cognos Proprietary Information

IBM Cognos Proprietary Information

IBM Cognos Proprietary Information

2 Enhancements to Prompt Caching

2.1 Dynamic Prompt Cache Refresh

IBM Cognos Proprietary Information

2.2 Multilingual Cache 1

To see this in action consider the following scenario and events:

A report is newly created with no prompt cache. The Dynamic Prompt

On day 3, a German language user runs the report. As there is no

On days 4 through 7, additional French and German users run the

IBM Cognos Proprietary Information

And so on, with language specific data being cached as required.

IBM Cognos Proprietary Information

2.3 Unilingual Cache

As it is difficult to demonstrate the advanced server property in action, a

IBM Cognos Proprietary Information

3 Reusable Toolbox Objects 3

Based on the report specification, custom HTML/JavaScript code to be added

IBM Cognos Proprietary Information

Toolbox.xml creates the structure of the toolbox determining which items

In toolbox.xml, the HTML item definition for example appears as so:

controlRef="HTMLItem" The id of the item as it appears in

ToolboxControls.xml defines the xml report snippets. Remember that the

IBM Cognos Proprietary Information

ToolboxControls.xml defines the item itself as so:

The id=”HTMLItem” property links the

</HTMLItem> Ends the definition

IBM Cognos Proprietary Information

3.1 Workshop: Re-Usable HTML Item

Open Report Studio with the GO Sales (query) package 8 .

Create a list report with

IBM Cognos Proprietary Information

Click OK and run the report:

The staticValue content contains somewhat cryptic information such as

IBM Cognos Proprietary Information

Insert a new line as in the highlighted text below:

Save and close the Toolbox.xml file.

IBM Cognos Proprietary Information

Add the ID to create the link back to Toolbox.xml:

Save and close this file.

Create a new list report using Product line:

IBM Cognos Proprietary Information

Run the report:

IBM Cognos Proprietary Information

Adding elements to the toolbox review:

IBM Cognos Proprietary Information

3.2 Workshop: Reusable Prompt Controls

This workshop will demonstrate how to create a reusable prompt so that an

Open Report Studio with the GO Sales (query) package.

Create a list report with:

Select the prompt.

Set the Query method to (Default).

IBM Cognos Proprietary Information

Add static values for:

Return to Report Studio.

Select the prompt and copy it to the Windows clipboard.

IBM Cognos Proprietary Information

We will name our prompt OrderMethodPrompt.

IBM Cognos Proprietary Information