8 Using Prompts and Parameters

This chapter contains information about using prompts and parameters.

This chapter contains the following topics:

About Prompts and Parameters

Parameters are similar to variables that represent substituted values. Prompts are dialog boxes displayed before the report opens so that the user can specify a parameter value. You can create prompts that display when a user views a report. The user must specify a value in the prompt dialog box which is used to limit or customize the view of data in the report. You can also create parameters that contain values. Parameters are not displayed to the user when the report is run.

You must apply prompts and parameters in a report by using them in filters. You can create prompts and parameters from the Report Properties dialog box or when you are creating a filter. The Prompts and Parameters page in the Report Properties dialog box provides a central way to manage, edit, and delete both prompts and parameters for the entire report.

After prompts and parameters are created, they are listed in by name in the Report Properties dialog box. The data type and default values display next to the prompt or parameter name. You can change the order that prompts display by arranging them in the list. The Arrange buttons and Preview buttons are disabled for parameters because they are not viewed by end users.

You can create alerts on reports that contain prompts or parameters, but only one alert action option is available. See "Send a parameterized message" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite for more information.

You cannot maintain alerts on reports if you add prompts or parameters to the report. The alerts become invalid and cannot be launched. You must re-create the alerts using the Send a parameterized message action.

Creating Parameters

You can create parameters in the Change Report Properties dialog box or in a filter when you specify a value. Creating parameters in the Change Report Properties dialog box does not make them active in the report until they are used in a filter. Parameters do not prompt the user to specify a value. The report designer specifies the value for a parameter.

To create a parameter:

  1. In a report that you are editing, click Change Report Properties.

    The Report Properties dialog box opens.

    Description of bam_report_prop_param.gif follows
    Description of the illustration bam_report_prop_param.gif

  2. Click New.

    The Prompt and Parameter Creation and Edit dialog box opens.

  3. In the Name and Data Type tab enter the following information:

    • Name: Enter a display name for the parameter

    • Parameter Type: Select a data type for the parameter value from the list.

    • Description: (optional) Enter a description for the parameter. This description is only displayed when the parameter is edited.

    • Value: To create a parameter containing a pre-defined value, select Use one of the values below (parameter), and select or enter the value to pass to the report parameter.

      To prompt the user for a value when the report is opened choose Prompt the user to specify a value, and continue with the procedure in "Creating Prompts".

    Description of bam_param_param.gif follows
    Description of the illustration bam_param_param.gif

  4. Click OK to save the parameter.

    The parameter is displayed in the Report Properties dialog box.

    Description of bam_param_list.gif follows
    Description of the illustration bam_param_list.gif

Creating Custom Parameters

Custom parameters are special parameters for Action Buttons that are available to every report in your Oracle Business Activity Monitoring installation. To create custom parameters you must edit the custom parameters data object in Oracle BAM Architect.

To create a custom parameter:

  1. Open Oracle BAM Architect and select Data Objects from the list.

  2. Select the Custom Parameters data object located in the Data Objects/System/Custom Parameters folder.

  3. Click Contents.

  4. Click Edit Contents.

  5. Click Add.

  6. Enter a name for the Custom Parameter. This name appears in the list of prompts and parameters available for Action Buttons.

  7. Enter the value for the Custom Parameter.

  8. Enter a short description for the Custom Parameter.

  9. Click Save.

Creating Prompts

You can create prompts that require the user to type in a value in a text field or to select one or more values from a list.

You can create prompts in the Change Report Properties dialog box or in a filter when you specify a value. Creating prompts in the Change Report Properties dialog box does not make them active in the report until they are used in a filter.

To create a prompt:

  1. Click Change Report Properties.

    The Report Properties dialog box opens.

    Description of bam_report_prop_param.gif follows
    Description of the illustration bam_report_prop_param.gif

  2. Click New.

    The Prompt and Parameter Creation and Edit dialog box opens.

  3. In the Name and Data Type tab enter the following information, and click Next.:

    • Name: Enter a display name for the parameter

    • Parameter Type: Select a data type for the parameter value from the list. The Datetime type presents additional options (see Creating a Datetime Type Parameter) and the Field type is a special case (see Creating a Field Type Parameter).

    • Description: (optional) Enter a description for the parameter. This description is only displayed when the parameter is edited.

    • Value: To prompt the user for a value when the report is opened choose Prompt the user to specify a value.

      To create a parameter containing a pre-defined value, select Use one of the values below (parameter), and continue with the procedure in Creating Parameters.

    Description of bam_param_name.gif follows
    Description of the illustration bam_param_name.gif

  4. In the User Input Type page, select a user input type.

    • Type in creates a text box in which the user must enter a value.

    • Choose from a list of field values creates a list of choices that the user must select from.

    Description of bam_param_input.gif follows
    Description of the illustration bam_param_input.gif

  5. In the Prompt message text field, enter the text that is displayed to the user in the prompt dialog box, and click Next.

    This text also appears next to the list in the report view if you chose Choose from a list of field values in the previous step.

  6. Configure the Input Definition.

    This tab appears differently depending on which user input type was selected in the previous screen.

    For Type in user input:

    If you selected the Type in user input type in the previous screen the Input Definition tab looks like this:

    Description of bam_param_typein.gif follows
    Description of the illustration bam_param_typein.gif

    1. Select a Default Value that can be a value that you supply, ALL, or NULL.

    2. Select User can leave value blank to allow this option.

      When using a Type in prompt, the user can type the following to indicate all, null, or blank values:

      • _ALL_ returns all values.

      • _NULL_ returns null values.

      • _BLANK_ returns blank values.

    3. Click Next.

    For Choose from a list of field values user input:

    If you selected the Choose from a list of field values user input type in the previous screen the Input Definition tab looks like this:

    Description of bam_param_def.gif follows
    Description of the illustration bam_param_def.gif

    1. Select the data object from which to get the values list.

      Click Change to select a data object. The fields in that data object populate the Field list.

    2. Select a field from the Field list. The values in that field populate the Values list.

    3. Select Choose values to exclude some values from the list. Then select the values that appear to the user.

      Note that when a datetime type field is selected, the values are displayed in the user's preferred time zone settings.

      Description of bam_prompt_time.gif follows
      Description of the illustration bam_prompt_time.gif

    4. Select a value and click Default Value to designate a starting value when the report is opened. A blue arrow appears next to the default value.

    5. Select ALL, NULL, or BLANK to add any of these values to the list.

    6. Select User can leave value unselected or User can select multiple values to enable these options.

    7. Click Next.

    The Summary page of the dialog box is displayed.

    Description of bam_param_summary.gif follows
    Description of the illustration bam_param_summary.gif

  7. Review your selections and click Preview to view the prompt you created.

    The Preview button is located in the lower left corner of the dialog box. The Prompts dialog box you created is displayed.

    Description of bam_param_prompt.gif follows
    Description of the illustration bam_param_prompt.gif

  8. Click OK to close the Prompts dialog box.

  9. Click OK to close the Prompt and Parameter Creation and Edit dialog box.

    The prompt is listed in the Prompts and Parameters list.

    Description of bam_prompt_list.gif follows
    Description of the illustration bam_prompt_list.gif

    You can now use this prompt in a filter. Then when a user opens the report, the prompt dialog box opens and waits for user input before the report is displayed, unless a default value was selected.

Creating a Datetime Type Parameter

When a parameter type of datetime is chosen you can also configure a time window (that is, you can filter the data by time) within which data is to be displayed by configuring the Now Mode. See Using Active Now for more information.

Description of bam_prompt_now.gif follows
Description of the illustration bam_prompt_now.gif

When using Now Mode in prompts and parameters, you can enter negative values for the Offset to select an interval in past.

Creating a Field Type Parameter

Field is a type that allows you to select data object fields as the values passed to the parameter, rather than values within a field. For example, choosing this type allows the user to change the field by which data is grouped in a chart while viewing a report.

While configuring the input definition for a parameter of type Field, you will choose only fields from the data object, and not values from a field.

When Field is chosen, and you select a field of type datetime, you are also presented with the option to create a time group. To add a time group, click Add. For more information about time groups see Configuring Time Groups.

Description of bam_prompt_timegrp.gif follows
Description of the illustration bam_prompt_timegrp.gif

The ALL, NULL, or BLANK values are not presented when creating parameters of prompts of type Field.

User can leave value unselected is not presented as an option when using the Field type.

Working with Prompts and Parameters

This section contains the following topics:

You can work with prompts and parameters from the Report Properties dialog box. Prompts and parameters created and edited from this dialog box belong to all the views in the report. They must be applied in a filter at the view level to become active. Managing prompts and parameters from the Report Properties dialog box means that you can make changes one time that might affect views in multiple areas.

Arranging Prompt Order

To arrange the prompt order:

  1. Select a prompt in the Report Properties dialog box.

  2. Click the Arrange arrows to move the prompt up or down in the list.

Previewing Prompts

To preview a prompt:

  1. Select a prompt in the Report Properties dialog box.

  2. Click Preview.

    The prompt dialog box opens.

Editing Prompts and Parameters

To edit a prompt or parameter:

  1. Select the prompt or parameter to edit.

  2. Click Edit.

    The Prompt and Parameter Creation and Edit dialog box opens containing the specified fields.

  3. Make changes as necessary and click OK.

  4. All filters in the report using this prompt or parameter value are updated.

Deleting Prompts and Parameters

To delete a prompt or parameter:

  1. Select the prompt or parameter to delete.

  2. Click Delete.

    The prompt or parameter is deleted. Any filters in the report using this prompt or parameter are also removed from the view.

Cascading Prompts

You can create prompts that are dependent on input from other prompts by cascading them.

To cascade prompts:

  1. Select a prompt and click Cascade.

  2. Enter the prompt message text to provide instructions in the prompt.

  3. Select the prompts in the cascade by selecting the check boxes.

  4. Arrange the prompts in the dependency order using the arrow buttons.

    Ensure that the order of cascading is relevant, that is, the first prompt should be a superset of the next one, and the next one should be the subset of the one before. Otherwise, the prompts do not work as expected if they are ordered incorrectly.

  5. Click OK. The prompts show their relationship in the Prompts and Parameters tab.

  6. Click OK to close the Report Properties Dialog Box.

Using Parameters in Report URLs

You can specify values for prompts and parameters in the URL displaying a report. This can be used in a separate browser such as a Web page in a portal site or as a link in an e-mail. You can view the report and click Copy Shortcut to copy the URL for the report. Then you can add, remove, or change the values for the prompts and parameters.

The syntax includes:

  • http://host:http_port/OracleBAM/buildnumber/ActiveViewer/ default.aspx?State=Start&Event=Initialize&NoWindow=True& ReportDef=reportnumber&Buttons=False

    The URL to call the report and display it in Oracle BAM Active Viewer. Copy this from the dialog box displayed when you click Copy Shortcut.

  • &ReportParameters=(PromptorParameterName=(PromptorParameterValue);)

    This section defines the value for one prompt or parameter. You can customize this by providing other values for prompts or parameters.

You can define values for multiple prompts or parameters, separated by semicolons, in any combination. Prompts included in the report that do not have a value defined in the URL display to the user for input.

The following example shows the syntax used for a report containing a prompt and a parameter:

http://host:port_number/OracleBAM/3091/ActiveViewer/default.aspx?State=Start& Event=Initialize& NoWindow=True&ReportDef=1364&Buttons=False&ReportParameters= (BrandPrompt=(Fuji); StateParam=(California);)

To set a prompt or parameter to all, null, or blank, you must use the following syntax to represent the values:

  • _ALL_ returns all values.

  • _NULL_ returns null values.

  • _BLANK_ returns blank values.

Driving Prompts and Parameters from Other Views

This section contains the following topics:

Changing a view by making a selection in another view is called Driving. Driving enables you to use a selection in one view to drive a prompt or parameter in another view. For example you might use a column in a List view to drive a Bar Chart view showing a graphical view of a subset of the data in the list.

To drive a view it must have a prompt or parameter that is used in a filter in the view (Action Form views do not have filters, so you only need to configure a parameter to use driving on an Action Form view) Also, drilling must not be enabled for driving to work. Drilling overrides driving.

The view that drives the other views, the Driver, is not required to contain a prompt or parameter, but there is some configuration involved.

Driving is available in all List and Crosstab views.

Configuring Driving

To configure driving:

  1. Create a parameter or prompt and use it in a filter in the target chart.

  2. Edit the driver view. The driver view is the view that is passing the value to the target view's prompt or parameter.

    Click the Properties button in the View Editor. To open the View Editor, double-click the view you are editing, or click Edit view in the View Tasks/Options list.

  3. Select the Driving tab.

  4. Select the prompt or parameter you created in step 1 for any column of data you want to use to drive views that are using that prompt or parameter in a filter.

  5. To enable driving on several values select the Turn Multi-select On check box.

    Multi-select enables you to select several values in a column. Multi-select only works if you have a prompt that enables multiple values configured in the view it drives.

  6. Click Apply or OK.

A Driving Example

The following is an example of driving a chart from a list view. This example uses the Call Center data object.

Step 1: Create a report with Streaming List and 3D Bar Chart views

  1. In Oracle BAM Active Studio, select the Home, My Reports, or Shared Reports tab.

  2. Click Create a New Report.

  3. Select a tiled report template with two view areas.

  4. In the top view area select the Streaming List view.

    The View Editor opens.

  5. In the View Editor, open the Samples folder and select the Call Center data object.

  6. Click Next.

  7. In the Data Fields selection screen, select all of the fields, and click Next.

  8. Click Finish.

  9. In the bottom view area select the 3D Bar Chart view.

    The View Editor opens.

  10. In the View Editor, open the Samples folder and select the Call Center data object.

  11. Click Next.

  12. Select Description in the Group By list.

  13. Select Quantity in the Chart Values list.

  14. Verify that Sum is selected in the Summary Function list.

  15. Click Next and click Finish.

Step 2: Create a filter with a prompt in the 3D Bar Chart view

  1. In the report, select the 3D Bar Chart view, and click Edit view in the View Tasks/Options list.

    The View Editor opens.

  2. Select the Filter tab.

  3. Click add new entry.

  4. Select Salesperson from the field list.

  5. Select is equal to from the Comparison list.

  6. Select Value.

  7. Click Options and select *New Parameter/Prompt.

    The Prompt and Parameter Creation and Edit dialog box opens.

  8. Enter Salesperson in the Name field and click Next.

  9. Enter Select a salesperson in the Prompt message text box and click Next.

  10. Select Salesperson from the Field list.

  11. Select the ALL check box.

  12. Select ALL in the Values list and click Default Value.

    An arrow appears next to the ALL value in the list.

  13. Select User can select multiple values and click Next.

  14. Click OK.

    The Prompt and Parameter Creation and Edit dialog box closes and the prompt expression appears in the Value field.

  15. Click add entry in the Filter tab.

  16. Click OK in the View Editor.

    The Prompts dialog box opens.

  17. Click OK.

    The 3D Bar Chart shows the quantity of each product description sold by all of the salespersons in the data object.

Step 3: Configure Driving in the Streaming List view

  1. In the report, select the Streaming List view, and click Edit view in the View Tasks/Options list.

    The View Editor opens.

  2. Click the Properties icon in the View Editor.

  3. Select the Driving tab.

  4. In the Map Fields to Prompts/Parameters list, select Salesperson in the list next to Salesperson.

  5. Click OK.

    The View Editor closes.

Step 4: Save the report and test the driving

  1. Click Save Report in the Actions list.

    The Save a Report dialog box opens.

  2. Select a name and location for the report and click OK.

  3. Click View in the Actions list.

    The prompt dialog box opens.

  4. Click OK.

  5. When the report is loaded, select Sue from the Salesperson column in the Streaming List view.

    The text color in the selected row changes so that you can see which Salesperson was selected. The bars in the Bar Chart view change to display the quantity of each product description sold by Sue.

Step 5: Configure Multi-select

Multi-select enables you to select several rows in a list to drive the chart. Multi-select only works if you configured the prompt to allow the user select multiple values as described in "Step 2: Create a filter with a prompt in the 3D Bar Chart view".

  1. Edit the Streaming List view.

  2. Select the Driving tab in the View Editor.

  3. Select Turn Multi-select On and click OK.

  4. Save the report and view it.

  5. When the report is loaded, select Sue from the Salesperson column in the Streaming List view.

    The text color in the selected row changes so that you can see which Salesperson was selected.

  6. Select Mary from the Salesperson column in the Streaming List view.

    The text in Sue's row stays colored, and the text in Mary's row is colored also. The 3D Bar Chart shows the quantity of each product description sold by both Sue and Mary.

  7. Select Mary again from the Salesperson column in the Streaming List view. The text color change is reversed, and the 3D Bar Chart shows Sue's sales only.