Ironside Tech Tip: Dynamic Default Prompts Done Right

Set Dynamic Default Prompts Using the New JavaScript Prompt API in IBM Cognos 10.2

Continuing with our Report Studio Cookbook series, today we will look at the new Report Studio JavaScript prompt API available in IBM Cognos 10.2. Since the very first release of the web based Report Studio, report authors have been asked often to use JavaScript in a report to achieve some common web application functionality, such as dynamically show/hide certain objects on page based on a user’s selection or changing a page’s color theme by data values. Ironside has published several articles illustrating how to use JavaScript in Report Studio; however undocumented JavaScript APIs and difficulties in migrating JavaScript after a Cognos upgrade have prevented many report developers from exploring this area.

In the latest IBM Cognos 10.2 release, a very welcomed new JavaScript prompt API is now available. With this new supported and documented JavaScript prompt API, it becomes much easier to write JavaScript applications to customize the standard prompt functionality in Report Studio.

In this article, we will work together in our Report Studio kitchen to prepare a simple report prompt page using the new prompt API. It will set dynamic default prompts based on data values.

Difficulty: Medium

Required Ingredients: Value Prompt

Scenario

Sales Manager Linda comes to you and asks: “Can you pre-set our monthly Sales by Country report to these countries? The list of these default selected countries could be changed over the period, though. Is that possible?”

As you know, most standard Cognos prompts have the flexibility to predefine default selections. It is very easy to use and often does fulfill the requirements. You simply set the Default Selections of a prompt on its Properties pane.

Linda’s request is a little bit different, as the default selections are “unknown” and changeable. An immediate thought would be to use JavaScript to check the prompt value at run time and set selections. Let’s take a look how to implement this using the new IBM Cognos 10.2 prompt API.

Steps:

1. Launch Report Studio, select the G0 Sales (query) package, and create a list report template when prompted.

2. Create a new prompt page. Drag in a new Value Prompt from the Toolbox.

3. Create a new parameter called Prompt – Country and use Country Code as the use values and Country as the display values from the Sales (query) namespace and Sales staff query subject.

Data item expression for Country: ..

Data item expression for Country Code: ..

(If you are not familiar with Report Studio please refer to the Report Studio User Guide).

4. Click on the newly created value prompt, go the Properties panel. Click on Data > Sorting and add Country to the Sort List (as shown below).

5. Enable Multi-Select by setting its value to Yes.

 

 

6. On the Properties pane, under Positioning, set the Size & Overflow property to 350 px.

 

7. Name the prompt countries.

Pro tip: The Name property is the tag that the prompt API will use to identify the value prompt control and it is case sensitive in JavaScript.

8. From the Toolbox, drag in an HTML Item and place it next to countries value prompt. Double click on the HTML item and type in the following JavaScript code:

<script type= text/javascript>

//<!–

function getPromptValue ( pName )

{

//get report

var oCR = cognos.Report.getReport(“_THIS_”);

//get prompt control

var oc = oCR.prompt.getControlByName(pName);

var promptValues = oc.getValues(true);

var v=new Array();

var j=0;

//loop through all prompt value, select those meet criteria

 for (var i = 0; i < promptValues.length; i++)

{//check whether country code value is less than 3000

if ( promptValues.use <3000)

{

v = { ‘use’: promptValues.use , ‘display’: promptValues.display }

j=j+1

}

}

oc.setValues(v);

}

getPromptValue( “countries”);

//–>

</script>

 

9. Run the report to test the prompt page. You should see that the countries Brazil, Canada, Mexico, and the United States are selected as dynamic default prompts.

Summary

The above sample shows how easy it is to develop a JavaScript application for dynamic default prompts using the new prompt API available in IBM Cognos 10.2. Similar techniques can be expanded to other types of prompts. The current prompt API allows authors to query and set user selections, validate typed-in values using patterns, set default values using expressions or query data, and more.

For a more personalized, hands-on tutorials and or issues with complex implementations, please contact Ironside today.