11 Creating Parameters

This chapter describes how to create parameters and prompts for queries, views, and dashboards in Oracle Business Activity Monitoring (BAM) to filter the data presented.

This chapter includes the following sections:

• Understanding Parameters

• Parameter Prerequisites and Uses

• Creating a Value Parameter

• Creating a List Parameter

• Using a Parameter in a Query

• Editing a Parameter

• Deleting a Parameter

• Securing a Parameter

• Using Parameters in Dashboard URLs

• Driving Parameters from Other Views

• Using Prompts in Dashboards

11.1 Understanding Parameters

A parameter is a variable representing the value of a data field.

A filter is a condition applied to data retrieved by a query or view, which can reference one or more parameters. A prompt is a request for the user to specify the value of a parameter. For example, you can filter a product sales query by country, create a parameter for the country, and prompt the user to choose the country when the query is referenced by a view in a dashboard.

A parameter can have a default, which can be a specific value or a special value such as ALL or NULL. For example, a product sales view could show sales for all countries by default.

There are two types of parameters: value parameters and list parameters. A value parameter can accept only one value and does not explicitly reference a specific data field. A list parameter can present and in some cases accept multiple values and references a specific data field.

Users can use datetime parameters, including the system datetime, to limit data based on a time span. Other datetime values are based on the time zone selected in user preferences.

11.2 Parameter Prerequisites and Uses

Parameter prerequisites are a set of tasks you must complete before you create a parameter, to ensure its smooth functioning.

Before you can create a list parameter, you must add to your project the data object containing the data field the parameter will represent. For more information about projects, see Planning and Creating Projects. For more information about data objects, see Working with Data Objects.

After you create parameters, you can use them in the following ways:

In a query

A query can reference parameters in filters. See Creating Business Queries for more information.

In a view

A view can reference a query that references parameters. However, you cannot do anything with a parameter in an individual view. See Creating and Using Business Views for more information.

In a dashboard

A dashboard can contain a view that references a query with parameters. The dashboard can prompt the user for the parameter values. See Creating Dashboards for more information.

In a parameterized message alert action

For queries or views that contain filters with parameters, only one alert action option is available. See Send a parameterized message for more information.

11.3 Creating a Value Parameter

This section outlines the procedure to create a Value Parameter.

To create a value parameter:

1. Go to the Designer page.
2. Select Parameters in the left panel navigator, or right-click Parameters and select the Create menu item.

   The Parameters dialog opens.

3. Type a Name and optionally edit the Display Name.

   The Name is case sensitive, must begin with a letter, and may consist only of letters, numbers, and the underscore character. It may have up to 128 characters. It cannot be changed after the parameter is created.

   The Display Name is case sensitive and may contain any characters except the forward slash (/), which indicates a folder path. It may have up to 128 characters. It can be changed at any time.

4. Select Value Parameter from the Parameter Type drop-down list, and click Create.

   A tab opens for the new parameter.

5. On the parameter tab, specify the following Parameter Definition settings:

   • Name — The name you selected in the Parameters dialog appears here.

   • Display Name — The display name you selected in the Parameters dialog appears here, where you can change it.

   • Description — Type an optional description for the parameter. This description is only displayed when the parameter is edited.

   • Data Type — Select the data type: String (VARCHAR), Datetime, Integer, Decimal, or Float.

   • Required — Check this box to require a value for this parameter. This value can be a default or a value chosen by the user.

   • Default Value — You must select a default value if Required is not checked. If Required is checked, a default is optional.

     Depending on the data type, the default value selection is different. The following options are displayed for all data types:

     • An Input Value text box in which you type the default value.

     • ALL, which returns all values.

     • NULL, which returns null values.

     The VARCHAR type also presents the user with Blank because these fields can be blank.

     The DATETIME type presents the user with a System Datetime option and a Select Date and Time icon.

6. Click Save.

11.4 Creating a List Parameter

This section outlines the procedure to create a List parameter.

To create a list parameter:

1. Go to the Designer page.
2. Select Parameters in the left panel navigator, or right-click Parameters and select the Create menu item.

   The Parameters dialog opens.

3. Type a Name and optionally edit the Display Name.

   The Name is case sensitive, must begin with a letter, and may consist only of letters, numbers, and the underscore character. It may have up to 128 characters. It cannot be changed after the parameter is created.

   The Display Name is case sensitive and may contain any characters except the forward slash (/), which indicates a folder path. It may have up to 128 characters. It can be changed at any time.

4. Select List Parameter from the Parameter Type drop-down list, and click Create.

   A tab opens for the new parameter.

5. On the parameter tab, specify the following Parameter Definition settings:

   • Name — The name you selected in the Parameters dialog appears here.

   • Display Name — The display name you selected in the Parameters dialog appears here, where you can change it.

   • Description — Type an optional description for the parameter. This description is only displayed when the parameter is edited.

   • Data Type — Select the data type: String (VARCHAR), Datetime, Integer, Decimal, or Float.

   • Required — Check this box to require a value for this parameter. This value can be a default or a value chosen by the user.

6. Specify the following Value Options settings:

   • Data Object — Select the data object containing the data field the parameter will represent.

   • Field — Select the data field the parameter will represent. Only fields of the selected Data Type are displayed.

   • Value Options — Select an initial value to display to the user in a prompt for this parameter. This can be one of the default values or a different value.

   • Choose Values — Check this box to require the user to choose a value for a Required parameter with no default. This makes responding to a prompt mandatory.

     If Required is checked and a default value is preconfigured, the user need not choose a value.

   • ALL — Check this box to allow ALL as a value.

   • NULL — Check this box to allow NULL as a value.

   • Blank — Check this box to allow a VARCHAR type field to be blank.

   • System Datetime — Check this box to allow the system datetime as the value for a DATETIME field.

   • User can select multiple values — Check this box to allow the user to select more than one value for this parameter when using a dashboard in the Viewer.

7. Specify the following Default Value settings:

   • Select Default Values — You must select at least one default value if Required is not checked. If Required is checked, a default is optional. To select a value, check the box to the left of the value in the drop-down list.

8. Click Save.

11.5 Using a Parameter in a Query

To be used, a parameter must be part of a query filter. When a query uses a parameter, a dashboard that contains a view that references the query prompts the user for the parameter value.

To reference a parameter in a query:

1. Create a parameter. See Creating a Value Parameter or Creating a List Parameter.
2. Create or edit a query. See Creating Business Queries for more information.
3. In the Filters panel of the query tab, click the New Filter icon.

   The Add/Edit Filter dialog appears.

4. Select the data field for the parameter from the drop-down list on the left.
5. Select the operation from the drop-down list in the center. The default operation is is equal to.
6. Select the radio button to the left of Select a Parameter.

   The Select a Parameter option is activated, and the other radio button options are grayed.

7. Select the parameter from the drop-down list.

   Value parameters of the same data type as the field you selected are included. List parameters based on the data field you selected are included.

8. Click OK to save the filter.
9. Click Save to save the changes to the query.

   If you configured an initial or default value for the parameter, the Input Values dialog appears.

10. Click OK to accept the parameter input value.

    A preview of the query uses the value you entered. See Creating Business Queries for more information.

11.6 Editing a Parameter

When you edit a parameter, the changes propagate to all queries that reference the parameter and all views and dashboards that reference these queries.

Use the following procedure to open, edit, and save a parameter.

To edit a parameter:

1. In the left panel navigator, click the arrow to the left of Parameters.

   All saved parameters in the current project are displayed in a list.

2. Click the parameter name, or right-click the parameter and select the Edit menu item.
3. Make the desired changes.
4. Click Save.

11.7 Renaming a Parameter

This section outlines the procedure to rename a parameter.

Use the following procedure to change the Display Name of a parameter.

The Display Name is case sensitive and may contain any characters except the forward slash (/), which indicates a folder path. It may have up to 128 characters. It can be changed at any time.

To rename a parameter:

1. In the left navigation pane, click the arrow to the left of Parameters.

   All saved parameters in the current project are displayed in a list.

2. To rename the parameter, right-click the parameter name and select the Rename menu item.

   The name becomes text in an editable field.

3. Type the new name and press Enter.

   The new name appears in the list.

When you edit the parameter, the new Display Name is displayed on the tab. This name is also displayed when you view the parameter in a dashboard.

However, the internal Name remains unchanged. When you edit the parameter, this name is displayed on the left in the header.

11.8 Deleting a Parameter

If you delete a parameter, it is removed from any queries, views, or dashboards that reference it.

Use the following procedure to delete a parameter.

To delete a parameter:

1. In the left panel navigator, click the arrow to the left of Parameters.

   All saved parameters in the current project are displayed in a list.

2. Click the parameter icon and click the Delete icon, or right-click the parameter name and select the Delete menu item.

   A dialog asks you to confirm the parameter deletion.

3. Click OK.

   The parameter disappears from the list.

11.9 Securing a Parameter

A parameter inherits security settings from the project in which it is created.

For more information about projects, see Planning and Creating Projects.

To change security settings for a parameter:

1. In the left panel navigator, click the arrow to the left of Parameters.

   All saved parameters in the current project are displayed in a list.

2. Right-click the parameter and select Security Settings from the pop-up menu.

   The security tab for the parameter opens.

3. To add a role or group to whom you can explicitly grant or deny permissions, follow these steps:

   1. Click the Add icon in the Grant Permissions or Deny Permissions table.

      The Add Application Roles, Groups, and Users dialog opens.

      See Managing Oracle BAM Users for information about how to add users to roles and groups.

   2. Type a Name for the role or group you are adding.

   3. Select from the drop-down List: Application Role or Group.

   4. Click Search to populate the Available Members list.

   5. To add a member to the Selected Members list, select the member and click the single right arrow.

   6. To add all members to the Selected Members list, select the member and click the double right arrow.

   7. To remove members from the Selected Members list, use the single and double left arrows.

   8. When the Selected Members list is final, click OK.

      The Add Application Roles, Groups, and Users dialog closes, and the Name you specified appears in the table.

4. To remove a role or group, select the table row and click the Remove icon.

5. To grant permissions, select Read, Write, Remove, or Security for the users, roles, and groups listed in the Grant Permissions table.

6. To deny permissions, select Read, Write, Remove, or Security for the users, roles, and groups listed in the Deny Permissions table.

7. Click Save.

11.10 Using Parameters in Dashboard URLs

You can specify parameter values in the dashboard URL. You can use this URL in a Web page in a portal site or as a link in an e-mail.

To display the default dashboard URL, right-click on the dashboard in the left panel navigator and select Show Dashboard URL. A pop-up dialog displays the URL, which you can copy and paste.

The syntax for a BAM dashboard URL is:

http://host:port/bam/composer/faces/proxypage?project=project&dashboard=dashboard&DashboardParameters=(parameter;parameter;...)

The syntax for a value parameter is:

name=value

The syntax for a list parameter is:

name=[value, value, ...]

For example:

http://mycompany.com:80/bam/composer/faces/proxypage?project=Sales&dashboard=Products&DashboardParameters=(Rep=ALL;Country=[US, UK])

You can define values for multiple parameters, separated by semicolons, in any order or combination. Parameters with no value defined in the URL prompt the user for input.

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.

11.11 Driving Parameters from Other Views

In a dashboard, 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 parameter in another view.

For example, you can use a column in a List view to drive a Bar chart view that shows a subset of the data in the list.

To be driven, a view must reference a query with a parameter used in a filter. Also, if drilling is enabled, driving will not work. Drilling overrides driving.

The view that drives the other views, the driver, need not reference a query with a parameter.

Figure 11-1 shows a dashboard with the Parameter Mapping Editor open. The Product data field value in the pie chart drives the fruitParam parameter value in the bar chart.

Figure 11-1 Parameter Driving Example

Description of "Figure 11-1 Parameter Driving Example"

For another example of a dashboard that uses parameter driving, see BPM Process View Dashboard.

To configure driving in a dashboard:

1. Click the Parameter Mapping Editor icon in the upper right corner of the dashboard tab.

   The Parameter Mapping Editor opens.

2. Select the view that will drive other views from the Source View drop-down list.
3. In the parameter mapping table, map the Source View data fields in the first column to the views in the remaining columns. Each cell in the table has a drop-down list of the parameters available for that view of the same data type as the Source View field.
4. Click OK to save the parameter mapping.
5. Click Save to save the dashboard.
6. Open the dashboard in the BAM Viewer (the Home page), in one of these ways:

   • On the Catalog tab, double-click a dashboard name.

   • On the Catalog tab, select a dashboard name and click the Open icon.

   • Under Most Recent or Favorites, click on a dashboard name if List View is selected or a thumbnail if Carousel View is selected.

   Observe how values in the source view are reflected in the driven views.

Note:

Drilling and driving operations can only be supported in the View Mode, and not in the Designer Mode. For new chart visualizations, driving is supported through the right click option. For graphs, no such menu option is available. You can click the graph element directly.

11.12 Using Prompts in Dashboards

When you open a dashboard in the BAM Viewer (the Home page), prompts for the associated parameters are displayed in the right panel.

Note:

Dashboard layout and size, label lengths, field lengths, and the number of prompts must be designed appropriately for prompts to be fully visible and operable. If there is not room on screen to display them all for a given report, you won't be able to see all the prompts.

To use a prompt for a parameter:

1. Open a dashboard in one of these ways:

   • On the Catalog tab, double-click a dashboard name.

   • On the Catalog tab, select a dashboard name and click the Open icon.

   • Under Most Recent or Favorites, click on a dashboard name if List View is selected or a thumbnail if Carousel View is selected.

2. If the right panel is not visible, display it by clicking the arrow in the middle of the right edge of the dashboard.

   The parameters associated with the dashboard are displayed in the right panel.

3. Change the parameter values as needed.

   Each value parameter has a text box in which you enter a value. Each list parameter has a drop-down list from which you select a value.

   The dashboard display changes each time you press Enter in a text box or select a new value from a drop-down list.

4. To revert to the parameter defaults, close and reopen the dashboard.