Setting Prompt Defaults Dynamically

For most prompt types in Cognos there is a Default property that allows for setting of static prompt defaults. This allows you to put in a specific value in advance and it works as advertised. However, there are many use cases where we want to dynamically set the default values to make the prompt interface more user-friendly. You might want to default the prompt to a common value that varies but still allow the end-user to change the value to their liking. Clearly, a way to set prompt values dynamically would be helpful.

The most common use for dynamic prompt defaults is setting date prompt initial state. By default, Cognos sets date prompt values to the current date. This includes range prompts where both the From and To date prompt controls will have the current date selected. This is often of little use to the user running the report as data warehouses often have data that is one day behind. In that instance, running a report for the current day would result in no data returned. Setting a common date dynamic date range can go a long way toward providing a richer experience and more user satisfaction with your reports.

The Technique

We will be using run-time JavaScript to set the defaults of a single date prompt which captures a date range for report filtering. The JavaScript outlined will only work in Cognos BI version 10.2 and above as I will only be using the Cognos JavaScript prompt API which wasn’t available in prior versions. This is a standardized way to access prompt objects which is documented and supporting by Cognos. Code written against the API should not break in later versions of Cognos BI.

Preparation

Before we can reference any Cognos prompt within JavaScript we have to provide a name for the prompt in the prompt object’s Name property. Ideally, the name should conform to JavaScript variable naming conventions. See the JavaScript Identifiers section of the w3schools.com JavaScript Variables Web page for more information. JavaScript compliant names allow us to use the same name to create reference variables in the code. This makes writing and maintaining the code much easier.

Assumptions

For our example code we will assume there is a date prompt on the page named dateRange which has its Range property set to Yes. We will be setting the default values to encompass the previous seven calendar days up to and including the previous day.

The Code

Let’s examine parts of the code in detail.

The Cognos JavaScript API function getControlByName() takes a prompt name and returns the Cognos JavaScript API object that represents that prompt. We assign the object reference to the variable dateRange so that we can use that name going forward. I recommend that you use a variable name that matches the name given the prompt in Cognos, for convenience and easier debugging but this is ultimately up to your own preference.

We create three new date objects to store the current date, the new from date, and the new to date. By subtracting days from the current date we get the from and to dates we want. We take the date objects and convert them to a date string of the format YYYY-MM-DD which is required by the Cognos JavaScript API for date prompts.

We call the addValues() Cognos JavaScript API function against the dateRange object to set the new default values. The function takes a JSON value object indicting the new values to use. For more information on the Cognos JavaScript API value object format see the Cognos documentation.

Notes:
We don’t need to indicate the display values in the value object we pass in. When setting the value of a prompt with the addValues() function the display value in the value object is ignored. This even holds true for value prompts where use and display values can be different.

We put our code in an if block in order to guarantee that the code only runs once. This is crucial when setting defaults because you want any prompt selections by users to be retained if the page is refreshed or reprompted. For more information on this technique see JavaScript: Running Code Only Once.

Conclusion

Cognos does not provide an easy way to set prompt values dynamically. However, by utilizing the JavaScript API provided by Cognos in version 10.2 and above we have a documented and supported method to manipulate prompts dynamically at run-time using the power of the JavaScript language.