Fabian's Business Intelligence BLOG

Last week a customer had the challenge that in a report a maximum of 5 stores should be selected in a prompt. This case I want to take to explain the new Cognos prompt api and it’s features. The prompt api is delivered in Cognos versions higher than 10.2.

First of all you need a handle to your report and to the user prompt. This can be done with the following functions:

var ocr = cognos.Report.getReport(„_THIS_“);
var ctrl=ocr.prompt.getControlByName(„TestControl“);

TestControl can be changed to the Name of your prompt. The returned object then the following methods for accessing a control:

• clearValues()
• setValues(<values>)
• <values>=getValues(<optionAll>)
• setValidator(<function (promptvalue)> )
• addValues(<values>)

<values> in this case is an array containing the following elements:

• use
• display
• start
• end

In this issue I will focus on the properties use and display, which are the use- and display-value of a user prompt.  If you want to clear the currently selected values you can use clearValues(). If you want to set the selected values you use the setValues(…) function with an array of the selected values. And getValues() returns an array with the selected items (if optionAll is set to false) or all items (optionAll=true). The setValidator function is used to add a handler function in case of a change event in the prompt. It was designed for adding functions that check the entered or selected value but can easily used for everything you want to do when the prompt selection changes. We see the correct use of setValues() and setValidator() functions later in the example code.

Unfortunately the addValues(values) function doesn’t work or at least I wasn’t able to use it correctly. But I also read that there is a bug. That means if you want to add items dynamically to the prompt you have to do it without the prompt api. For that you can check my articles on JavaScript & Cognos Part 1 & Part 2.

Back to the example of the beginning: We want to implement a function that counts the selected elements in a list and deletes the last selected item(s).

The first two rows receive handles on the report and the specific control. We use the control-handle and the setValidator function to connect the handler function to the control. The handler- function is expected to have one parameter which is used to pass the selected values. In our case we name it promptValue and it is an array.

In the function itself we first check the length of the array. In our case a maximum of 5 items can be selected. If there are more values selected we inform the user and return false.

The validator function always has to return true or false. If the validator function returns false, the prompt is marked in red and the user has to change his selection until the validator function returns true. Otherwise it’s not possible to finish the report.

It is also possible to correct the selected values automatically. For that one should remove the “return false” statement and put the following instead:

                               promptValue.splice(5,promptValue.length-5);
                               ctrl.setValues(promptValue);

These two lines remove the last items that are too much and re-sets the selected values to the prompt again. Of course you can do it in a better way but it’s just an example to show how to manipulate the user’s selection.

I hope this small example gave you an impression of what is possible with the prompt api and what not. In my opinion it was a good idea to introduce this api as there are many java script issues in adding dynamical interactions to the user prompts. With that api it’s easier to do that and saver for future updates. But still a lot of customers are using versions lower than 10.2 and they have to do it the classic way.

If you are interested in this or other advanced Cognos/SQL topics you can also attend training on my corporate homepage. At the moment my open courses are only available in German. Inhouse training and online courses are also available in English language. So check out my open trainings (German) or my online courses (English)!