Adding Prompts

You can add prompts to a report to add interactivity for users. Prompts act as questions that help users to customize the information in a report to suit their own needs. For example, you create a prompt so that users can select a product type. Only products belonging to the selected product type are retrieved and shown in the report.

Prompts are composed of three interrelated components. Parameters, which are based on parameterized filters, form the questions you want to ask users. Prompt controls provide the user interface in which the questions are asked. Finally, parameter values provide the answers to the questions.

Report Studio provides several ways to create prompts. You can

• define prompts using context filters

• use the Build Prompt Page tool

• build your own prompt and prompt page

• create a parameter to produce a prompt

• insert prompts directly into the report page

If you include reports from different packages in an interactive dashboard that uses global filters, ensure that you use the same parameter name for the prompt in all the reports. For more information about creating interactive dashboards, see the Administration and Security Guide.

You can also create prompts in the package. For more information, see the Framework Manager User Guide.

Define Prompts Using Context Filters

If context filters (or slicers) are defined, you can use these filters to create prompts in the report. Prompts provide questions that help users to customize the information in a report to suit their own needs. For example, you create a prompt so that users can select a region. Only data for the specified region is retrieved and shown in the report.

Before you define a prompt, you must create context filters .

Steps

1. In the Context filter section of the overview area, click the down arrow next to the filter that you want to use as a prompt.

2. Click Prompt.

3. Do one of the following:

   • To remove the prompt, click No Prompt.

   • To allow users who run the report to select any member from a tree of the hierarchy, click Prompt on Hierarchy.

   • To allow users who run the report to select from a list of members from the current level, click Prompt on Level.

Use the Build Prompt Page Tool

Use the Build Prompt Page tool to quickly add prompts to a report. Report Studio creates the prompts for you in a default prompt page.

Steps

1. Click the column you want users to be prompted on.

   To create multiple prompts or a cascading prompt, click more than one column.

2. From the Tools menu, click Build Prompt Page.

   A prompt page is created that has:

   • a page header

   • a prompt control for each selected column

   • a page footer containing Cancel, Back, Next, and Finish prompt buttons

You can add more objects or modify existing elements. For example, you can change the prompt control chosen by Report Studio.

Build Your Own Prompt and Prompt Page

Create your own prompt and prompt page to control how they appear in a report.

Steps

1. Pause the pointer over the page explorer button  and click Prompt Pages.

2. In the Insertable Objects pane, on the Toolbox tab, drag Page to the Prompt Pages box.

3. Double-click the page you just created.

4. In the Insertable Objects pane, on the Toolbox tab , drag one of the following prompt controls to the prompt page.

   Prompt control	Description
   Text Box Prompt	Retrieves data based on a value that you type. Use this control when users know exactly what value they want to enter, such as a name or account number.
   Value Prompt	Retrieves data based on values that you select from a list. Use this control to show the list of possible values from which users can choose. Note: The maximum number of items that can appear in a list is 5000.
   Select & Search Prompt	Retrieves values based on search criteria that users specify. Data is then retrieved based on values users select from the search results. Use this control instead of a value prompt if the list of values is very long, which can slow down performance. Tip: Users have the option of performing a case sensitive or case insensitive search. A case sensitive search is faster, while a case insensitive search usually returns more values. You cannot use this control if you are working with SAP BW data sources.
   Date Prompt	Retrieves data based on a date that you select. Use this control when you are filtering a date column. With this control, users can retrieve data for a specific day, a set of days, or a range of days.
   Time Prompt	Retrieves data based on a time that you select. Use this control to restrict a report to a particular time or time range. For example, you can use this control to see how many orders are received after business hours. You can then use this information to determine the number of staff needed to work after hours.
   Date & Time Prompt	Retrieves data based on a date and time that you select. Use this control when you are filtering a datetime or timestamp column. This control is useful for specifying ranges. For example, you can retrieve all orders received from Monday at 12:00 a.m. to Friday at 5:00 p.m.
   Interval Prompt	Retrieves data based on a time interval that you specify. Use this control to retrieve data that is related to the passage of time. For example, you can use this control to retrieve a list of products that were returned 30 or more days after they were purchased.
   Tree Prompt	Retrieves data based on values you select from a list. Values are organized hierarchically. This control is useful when you are working with dimensional data sources. Data is shown from the top of a dimension hierarchy to the most detailed member, and users can choose the level of detail they want to view in the report. For more information about tree prompts, see Control the Data That Appears in a Tree Prompt.
   Generated Prompt	Selects a prompt control based on the data type of the data item. This control acts like a placeholder. When you run the report, the control is replaced by the appropriate prompt control. For example, if you are prompting date values, the control is replaced by a date & time prompt.

   The Prompt Wizard dialog box appears.

5. If you are creating a text box, date, time, date and time, interval, or generated prompt, do the following:

   • Create a new parameter for the prompt or use an existing parameter.

   • Click Next.

   • If you create a new parameter, define the expression by selecting a data item from the package and the operator you want to use.

     Tip: Make the prompt optional by selecting the Make the filter optional check box. When selected, users will not be required to choose a value when the report is run.

   • Go to step 8.

6. If you are creating a value, select & search, or tree prompt, do the following:

   • Create a new parameter for the prompt or use an existing parameter.

   • Click Next.

   • If you created a new parameter, and you want to use the parameter to filter data, select the Create a parameterized filter check box and define the expression by selecting a data item from the package and the operator you want to use.

     If you are creating a tree prompt, you must choose in in the Operator box.

     You can use parameters for other purposes besides filtering data. For example, you can use a parameter to provide a value for a layout calculation, such as showing a user’s name in the report. When the report is run, you can use a parameter to prompt the user to type his name and have it appear in the report.

     Tip: Make the prompt optional by selecting the Make the filter optional check box. When selected, users will not be required to choose a value when the report is run.

   • Click Next.

   • If you created a parameterized filter and you have more than one query defined in the report, select the query you want to filter and then click Next.

   • Select the Create new query check box to create the query that will be used to build the list of data values shown when the report is run.

     Tip: Do not create a new query if you want to link the prompt to an existing query or if you intend to create the query at a later time.

   • Click the ellipsis (...) button beside Values to use and click the data item you want to prompt on.

     Tip: You can choose a data item that is different than what users will see when they are prompted (see the following step). For example, you want to prompt on Product line. The package contains the data items Product line and Product line code. You can choose Product line code as the values to use for faster data retrieval.

   • Click the ellipsis (...) button beside Values to display and click the data item that you want users to see when they are prompted.

   • To create a cascading prompt, click the Cascade Source box, and select the parameter that represents the cascade source.

7. Click Finish.

The prompt control is added to the prompt page. A prompt page is like a report page. You can insert graphics, text, and so on, and apply any formatting you want.

You can also modify the properties of the prompt control by clicking it and making changes in the Properties pane.

Example - Create a Report Showing Products Shipped for a Specific Time Interval

You are a report author at the Great Outdoors Company, which sells sporting equipment. You are requested to create a report that shows the time interval between closing and shipping dates.

Steps

1. In the Cognos Connection Welcome page, click the Public Folders link.

2. Click the GO Data Warehouse (query) link, click the Launch link in the upper-right corner of the page, and then click Report Studio.

3. In the Welcome dialog box, click Create a new report or template.

4. In the New dialog box, click List and click OK.

5. In the Insertable Objects pane, on the Source tab , expand Sales and Marketing (query) and Sales (query).

6. Expand Sales order and add Order number to the list by double-clicking it.

7. Expand Product and add Product name to the list by double-clicking it.

8. Expand Sales fact. Add Quantity to the list by double-clicking it.

9. In the Insertable Objects pane, on the Toolbox tab, drag Query Calculation to the right of Return quantity in the list.

10. In the Name box, type the following and click OK:

    Time Interval

11. In the Expression Definition box, type the following and click OK:

    [Sales (query)].[Time dimension (close day)].[Date (close day)]-[Sales (query)].[Time (ship date)].[Date (ship date)]

12. From the Data menu, click Filters .

13. Click the add button.

14. In the Expression Definition box, type

    [Sales (query)].[Time dimension (close day)].[Date (close day)]-[Sales (query)].[Time (ship date)].[Date (ship date)] > ?p1?

15. Click OK twice.

    A parameterized filter is created that will return data when the difference between the return date and the order date is greater than the value specified by the user.

16. Pause the pointer over the page explorer button  and click Prompt Pages.

17. In the Insertable Objects pane, drag Page to the Prompt Pages pane, and then double-click it.

18. In the Insertable Objects pane, on the Toolbox tab , drag Interval Prompt to the work area.

    The Prompt Wizard dialog box appears.

19. Click Use existing parameter, and then click p1.

20. Click Finish.

21. Run the report.

    An interval prompt appears.

22. In the Days box, type a value and click Finish.

    Tip: You can also type values for the Hrs and Mins boxes.

A list report appears, showing all products that were shipped after the time interval you specified. For example, if you type 5 days, the list will show products that were shipped more than 5 days after the order date.

Create a Parameter to Produce a Prompt

Report Studio can automatically generate prompted reports based on parameters you create. When you run the report, Report Studio can generate a prompt page for each parameter not associated to an existing prompt page, depending on whether the prompt run option is selected or not.

You also define parameters when you want to create a drill-through report , and you can use parameters to define master detail relationships .

Steps

1. From the Data menu, click Filters .

2. On the Detail Filters tab, click the add button.

   The Detail Filter dialog box appears.

3. In the Available Components box, click the source or Data Items tab to select the data item you want to use for the prompt:

   • To filter data based on data items not shown in the report, double-click a data item on the Source tab .

   • To filter data that appears in the report but not necessarily in the model, such as calculations, double-click a data item on the Data Items tab .

   The data item appears in the Expression Definition box.

4. In the Expression Definition box, type an operator after the data item, or select an operator from the Functions tab.

   The operator sets some of the default properties of the prompt. For example, if the operator is equals (=), users will be able to select only a single prompt value, and the prompt's Multi-Select property is set to No.

   For more information about creating expressions, see Using the Expression Editor.

5. Type a name after the operator to define the prompt parameter. A question mark must precede and follow the name.

6. Click OK.

7. In the Usage box, click one of the following:

   • To create a required prompt, click Required.

   • To create an optional prompt, click Optional.

   • To specify not to use the prompt, click Disabled.

8. Click OK.

Create a Prompt Directly in a Report Page

You can add prompt controls directly in a report page instead of creating a prompt page.

Prompt controls that are added to report pages will not appear in the following:

• saved reports

• PDF reports

• reports that are sent to users by email

• scheduled reports

Prompt controls are by their very nature interactive. They are used to satisfy parameter values before running a report. As a result, prompt controls added to a report page only appear when you run the report in HTML format. When you run a report in HTML format, users select which values they want to see, and the report is refreshed, producing a new report.

For the non-interactive reports listed above, prompt parameter values must be collected and satisfied before the report is run. You provide the parameter values you want using the Run options tab in Cognos Connection. If you do not provide all the required values, the report will fail to run. You can access the Run options tab by clicking the set properties button  for the report.

If you are using the sample reports that come with Report Studio, the reports Consumer Trends, GO Media, Product Line by Year-prompt, and Sales Representative Contact List contain prompt controls on report pages.

Steps

1. In the Insertable Objects pane, on the Toolbox tab , drag a prompt control to the location where you want it to appear.

   The Prompt Wizard dialog box appears.

2. Provide the information necessary to create the prompt.

   Tip: Make the prompt optional by selecting the Make the filter optional check box. Otherwise, when you run the report for the first time, the prompt appears in a generated prompt page rather than in the report page. Alternatively, you can specify a default selection for the prompt .

3. In the work area, click the prompt.

4. In the Properties pane, set the Auto-Submit property to Yes.

   If you do not set the Auto-Submit property to Yes, the report will not refresh when users select a different prompt value.

   Tip: An alternative to setting the prompt to auto-submit is to add a prompt button from the Toolbox tab and setting its Type property to Finish.

The prompt control is added to the report page. You can modify its properties by clicking it and making changes in the Properties pane.

Modifying Prompts

For each prompt you create, you can modify its properties by specifying values in the Properties pane. For example, you can

• change the prompt control interface

• specify that a prompt requires user input

• allow users to select multiple values

• show or hide prompt status

• specify default selections

• specify prompt values

• add a prompt button

• create a cascading prompt

Some properties you set for a prompt may be overridden under some conditions. For example, some properties set for the filter associated with a prompt may override the corresponding prompt property.

Change the Prompt Control Interface

By default, when you create a prompt, Report Studio selects the prompt control interface. You can change the prompt control interface to something different, depending on the type of prompt you created. For example, for a value prompt, you can choose a drop-down list, a list box, or a radio button group.

Steps

1. Click the prompt control you want to modify.

2. In the Properties pane, click the Select UI property and click the interface you want.

Specify That a Prompt Requires User Input

You can specify that a prompt requires user input before the report can run.

Steps

1. Click the prompt control you want to modify.

2. In the Properties pane, click the Required property and click Yes.

3. Pause the pointer over the page explorer button and go to a report page.

4. From the Data menu, click Filters .

5. Click the filter associated with the prompt.

6. In the Usage box, click Required and then click OK.

When you run the report, a star appears next to the prompt indicating that the user must select or type a value.

If you have a cascading prompt and the parent prompt control is required, the child prompt control is disabled. This ensures that users choose at least one value in the parent prompt before they can choose a value in the child prompt. Conversely, if the parent control is optional, then the child control is populated. This gives users the ability to choose values in the child prompt without having to choose a value in the parent prompt.

Allow Users to Select Multiple Values in a Prompt

You can allow users to select more than one value or a range of values in a prompt. For example, you have a prompt for which users must select a product line. You can modify the prompt so that users can select more than one product line.

If you enable multiple selections, the Auto-Submit property is always set to no.

Steps

1. Click the prompt control that you want to modify.

2. In the Properties pane, choose whether to allow users to specify more than one value or a range of values:

   • To allow users to specify more than one value, set the Multi-Select property to Yes.

   • To allow users to specify a range of values, set the Range property to Yes.

3. Pause the point on the page explorer button and go to a report page.

4. From the Data menu, click Filters .

   If you have more than one query defined in the report, you must first click an object linked to a query. If there is more than one query defined in the report, click an object that is linked to the query you want.

5. Double-click the filter associated with the prompt.

6. Change the operator to one of the following:

   • If you are creating a multi-select prompt, change the operator to in.

     For example,[Product_line] in ?Product line?, where [Product_Line] is the name of the data item, allows users to select multiple product lines.

   • If you are creating a range prompt, change the operator to in_range.

     For example, [Margin] in_range ?Margin?, where [Margin] is the name of the data item, allows users to specify a margin range.

7. Click OK twice.

Show or Hide Prompt Status

Each prompt you create in a report provides dynamic validation when the report is run. Validity checks are performed to ensure that the data is correct, and that required values are supplied. For example, a star appears next to each required prompt. An arrow appears next to a prompt if you must select or type a value. If you type an incorrect value, a dotted line appears. You can choose whether to show the star and arrow for each prompt.

Steps

1. Click the prompt control you want to modify.

2. In the Properties pane, click the Hide Adornments property and click Yes to hide the prompt characters or No to show them.

Specify a Default Selection for a Prompt

You can specify a default selection for a prompt so that users do not have to select or type a value when they run the report.

Steps

1. Click the prompt control that you want to modify.

2. If you want to define a range of values, in the Properties pane, set the Range property to Yes.

3. If you want to specify more than one default selection, set the Multi-Select property to Yes.

4. In the Properties pane, double-click the Default Selections property.

5. Click the add button , and do one of the following:

   • If you chose to define a single value, type the value you want as the default selection.

   • If you chose to define a range of values, type the minimum and maximum values of the range in the Minimum value and Maximum value boxes, respectively.

6. Click OK.

7. Repeat steps 4 to 5 to specify other default selections.

8. Click OK.

Specify Prompt Values

Provide your own values in a prompt

• to show something different from what is in the database

• to improve performance by not accessing the database

• to provide text for optional prompts, such as Select a value

• to restrict the number of values available

For example, you have a prompt in which users choose a country. For the database value United States, you want USA to appear in the prompt.

Steps

1. Click the prompt control that you want to modify.

2. In the Properties pane, double-click the Static Choices property.

3. Click the add button .

4. In the Use box, type the prompt value you want to add.

5. In the Display box, type the value that will appear in the prompt.

6. Click OK.

7. Repeat steps 4 to 7 to add other prompt values.

8. To link a prompt value to a condition , do the following:

   • Click the Variable drop-down list and choose the variable you want to use or create your own.

     For information about creating variables, see Add a Variable.

   • Click the Value drop-down list and click one of the possible values for the variable.

   • Click the static value you want to link to the variable and click the edit button .

   • In the Display box, type the value that you want to appear in the prompt for that particular value of the variable.

   • Repeat this procedure for each additional value.

9. Click OK.

Add a Prompt Button

Add prompt buttons so that users can submit selected items, cancel a report, or navigate between pages.

When you are building prompts and prompt pages , you may have to add a prompt button to submit selections. Some prompt controls, such as the value prompt, can be set to submit selections automatically. Other prompt controls, such as the date prompt, require a prompt button.

Steps

1. Pause the pointer over the page explorer button  and click the report or prompt page that contains the prompt control for which you want to add a prompt button.

2. In the Insertable Objects pane, on the Toolbox tab, drag Prompt Button  to the work area.

3. Click the prompt button and in the Properties pane, click the Type property. Choose one of the following actions.

   Goal	Action
   Cancel the report	Cancel
   Go to the previous prompt page	Back
   Go to the next prompt page	Next
   Run the report	Finish
   Reprompt the user Tip: Reprompting users is useful when you have cascading prompts.	Reprompt

Create a Cascading Prompt

Create a cascading prompt to use values from one prompt to filter values in another prompt. For example, a report contains the columns Product line and Product type. You create prompts for these columns, and you specify that the Product type prompt is a cascading prompt that uses Product line as the cascading source. When users select a product line, they see only the product types related to the selected product line.

Steps

1. To make the cascading source a required prompt, click it and in the Properties pane, set the Required property to Yes.

2. Click the prompt control that you want to use as a cascading prompt.

3. In the Properties pane, double-click the Cascade Source property.

4. Click the parameter that represents the cascade source, and click OK.

5. If the prompt allows users to select multiple values, add a prompt button to the cascade source to provide the cascading prompt with the appropriate values:

   • In the Insertable Objects pane, on the Toolbox tab, drag Prompt Button  to the report.

   • Click the prompt button and in the Properties pane, click the Type property and click Reprompt.

   • To change the text in the prompt button, in the Insertable Objects pane, on the Toolbox tab, drag Text Item  to the prompt button and type the text you want.

For more information about how to create cascading prompts, see the Report Studio Tour.

Control the Data That Appears in a Tree Prompt

You can control what data appears in a tree prompt and how the data is structured to get the results that you want. To do this, you add various functions to the filter expression.

In addition, the operator that you chose in the Prompt Wizard dialog box controls what appears next to each prompt value. If the operator is in or not in, check boxes appear next to each prompt value. If the operator is equals (=), no check boxes appear.

Steps

1. Pause the pointer over the query explorer button  and click the query that is associated with the prompt.

2. In the Data Items pane, double-click the data item that you are prompting on.

3. In the Expression Definition box, type one of the following functions and click OK.

   Goal	Function
   Show the hierarchical structure of all members in the hierarchy. If this function is not used, all members are shown in a flat list.	rootmembers(data_item)
   Show the descendants of the data item in a hierarchical structure, where x represents the level. For example, if you are prompting on the Year hierarchy, and x=1, you will see 2004, 2005, and 2006 in the tree. If x=2, you will see 2004 Q1, 2004 Q2, and so on.	descendants(rootmembers(data_item, x)
   Show the children of a member. For example, 2004 Q1, 2004 Q2, 2004 Q3, and 2004 Q4 appears for the member 2004.	children(member)