Professional Documents
Culture Documents
Advanced Prompting Ibm Cognosbi83 84
Advanced Prompting Ibm Cognosbi83 84
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.
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.
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.
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.
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 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.
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.
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:
<!-- HTML Item -->
<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.
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.
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.
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.
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.
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>
<staticValue>This is <b>MY</b> HTML item.</staticValue>
</dataSource>
</HTMLItem>
Open Toolbox.xml.
<resources>
<!--
Categories
==============
A = Basic
B = Text items
C = Prompting
-->
<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.
Open ToolboxControls.xml.
Copy and paste the new HTML item definition into this file:
<!--
Copyright (C) MyCompany Incorporated. All Rights Reserved.
-->
<resources>
<xmlFragment id="ToolboxControls">
<!-- Custom HTML Item -->
<HTMLItem>
<dataSource>
<staticValue>This is <b>MY</b> HTML item.</staticValue>
</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.
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.
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.
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.
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.
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.
Run the report and test the various static values to make sure that they
match the requirements of the query filter expression.
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>
Open Toolbox.xml.
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.
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?)
Drag the new Order Method Prompt from the Toolbox into the layout of the
new prompt page.
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.
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.
9
Or into a report page as appropriate
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.
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.
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.
Select Product line and press the Build Prompt Page toolbar button.
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>
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.
Page down and notice that the Quantity values start at 1 and go to much
higher values.
Drop the Beer Glass Prompt into the new prompt page.
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.
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.
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.
Create a new filter with Product number: [Product number] >= ?ProdNum?
The HTML item used to define the custom dynamic picklist control shows up
in the report as so:
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
'<script Tells the browser which file
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:
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:
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.
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.
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.
As so:
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.
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.
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.
Select the conditional block and set the Block Variable property to
SelectedTab.
When the Wizard starts, set the parameter to use the existing ProdLine
parameter.
Click Next.
Click Next.
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.