Print      Open PDF Version of Online Help

Administering Oracle CRM On Demand > Application Customization > Record Type Application Customization Page > About Specifying Filters for Embedded Reports and Dashboards

About Specifying Filters for Embedded Reports and Dashboards

You can embed reports and dashboards in custom Web applet and Web tabs. You can also configure Web link fields to open reports and dashboards.

When you create a custom Web applet, Web tab, or Web link of the Report or Dashboard type, you can specify filters that will be applied at run time. For a dashboard, the filters that you specify apply to all of the reports in the dashboard.

Each of the columns that you specify in the filters must also have a filter configured for it in the report that you want to embed, and if you are embedding a dashboard, then the column must have a filter configured for it in each of the reports in the dashboard. The filter in the report can be set to "is prompted" or configured with an operator and a value. If a filter is not configured for a column in the report, then any filter that you specify for that column in the Web applet, Web tab, or Web link will not be applied when the report is run. For information about adding filters to columns in reports, see Adding Filters to Columns in Analytics.

NOTE: When you create a custom Web applet, Web tab, or Web link of the Report type, you can optionally specify that any prompts that are defined for the embedded report are to be displayed at run time, by selecting the Display Report Prompts check box. Displaying prompts at run time allows users to filter the report. However, the setting in the Display Report Prompts check box takes precedence over any filters that are defined in the Parameters field for the embedded report or dashboard. Therefore, if you select the Display Report Prompts check box for a custom Web applet, Web tab, or Web link, then any filters that are defined in the Parameters field as described in this topic are ignored, even if no prompts are defined for the embedded report.

Syntax for Specifying Filters

You can specify the parameters for filters in either of the following ways:

• Using the Pn parameters, which is referred to as the Pn syntax.
• Using groups of the opn, coln, and valn parameters, which is referred to as the opn syntax.

You cannot use a mixture of the two types of syntax.

Using the Pn syntax, you can specify a maximum of six filters. In the P0 parameter, you specify the number of filters that you want to set up. The valid values for the P0 parameter are integers 1 through 6. The P0 parameter can be used only once in the parameter string. Each filter uses three parameters to contain the operator, the column, and the value. You specify the first filter in parameters P1-P3. P1 must specify the operator, P2 must specify the column, and P3 must specify the value. You specify the subsequent filters in sets of three parameters, namely P4-P6, P7-P9, P10-P12, P13-P15, and P16-P18. You must use an ampersand (&) to separate the parameters. Each parameter can be used only once in the parameter string.

For a single filter, the syntax is as follows, although the parameters can be placed in any order in the parameter string:

P0=1&P1=operator&P2=table.column&P3=value

To specify additional filters, you add parameters P4-P6, P7-P9, and so on, and increase the value of the P0 parameter to match the number of filters that you add. So, for two filters, the syntax is as follows:

P0=2&P1=operator&P2=table.column&P3=value&P4=operator&P5=table.column&P6=value

Using the opn syntax, there is no limit to the number of filters that you can specify. Each filter uses a group of three parameters: the opn parameter specifies the operator, the coln parameter specifies the column, and the valn parameter specifies the value. You must use an ampersand (&) to separate the parameters. You must number each of the parameters in a filter group with the same number, which must be an integer greater than 0 (zero), and you must number the groups of parameters sequentially. For a single filter, the syntax is as follows, although the parameters can be placed in any order in the parameter string:

op1=operator&col1=table.column&val1=value

Similarly, for two filters, the syntax is as follows:

op1=operator&col1=table.column&val1=value&op2=operator&col2=table.column&val2=value

NOTE: In the column parameter, if a table name or a column name contains a space, then you must enclose that name in double quotation marks. If a table name or a column name does not contain a space, then you do not need to enclose the name in double quotation marks, but you can do so if you wish. This is true for both types of syntax.

Page Parameter

When you embed a dashboard, you can also optionally use the Page parameter to specify which page of the dashboard opens when the dashboard is rendered. The syntax for the Page parameter is:

Page=page name

where page name is the name of the page as it appears in the dashboard. Do not enclose the page name in double quotation marks, even if the name contains one or more spaces. You can specify the Page parameter on its own or with other parameters. You can place the Page parameter in any location in the parameter string, but you must use an ampersand (&) to separate the Page parameter from any parameter that precedes it or follows it.

The Page parameter is not validated when you save the parameters. If you do not include the Page parameter, or if you include it but leave the parameter value blank, then the first page of the dashboard opens when the dashboard is rendered. If you specify a value that is anything other than the valid name of a page in the selected dashboard, then an error is displayed at run time.

About Special Characters in Parameters

If a table name, column name, value, or dashboard page name that you specify in a parameter includes any of the following characters, then the character must be encoded, as follows:

• % (percent sign). Encode as %25.
• & (ampersand). Encode as %26.
• [ (left bracket). Encode as %5B.
• ] (right bracket). Encode as %5D.
• + (plus sign). Encode as %2B.

If these characters are not encoded, then an error might be returned when you try to save the parameters, or the results might not be correct at run time.

Parameter Validation

With the exception of the Page parameter, the parameters that you specify are validated when you try to save your changes. If any errors are detected, then you must fix those errors before you can save your changes.

NOTE: In releases earlier than Release 40, the filter parameters were not validated before they were saved. Therefore, a filter parameter that was specified for an embedded report or dashboard in a release earlier than Release 40 might contain an error. If any errors are detected in the syntax of a filter when an embedded report or dashboard is rendered, then an error message is displayed. Also, if you edit an existing Web applet, Web tab, or Web link field of the Report or Dashboard type, and if you make a change to any field, then when you attempt to save your changes, all of the fields including the Parameters field are validated. If any errors are detected, then you must fix those errors.

The following sections describe the parameters that make up a filter.

Operator

The following table lists the operators that you can use in a filter.

Column

When specifying the column, note the following points:

• You must specify both the table name and the column name, separated by a period (.).
• If a table name or a column name contains a space, then you must enclose that name in double quotation marks. If a table name or a column name does not contain a space, then you do not need to enclose the name in double quotation marks, but you can do so if you wish. This is true for both types of syntax. For example, all of the following are valid:

  "Account"."Account Name"

  "Service Request".Area

  Account."Account Name"

• You must use the original column names, and not the display names.

Value

When specifying the value for a filter, note the following points:

• You can specify a value directly, or you can specify a field as a parameter.
• If you use the opn syntax, and if you directly specify a value that contains a space, then the value must be enclosed in double quotation marks. If more than one value is specified, and if any one of the values contains a space, then each of the specified values must be enclosed in double quotation marks, for example:

  val1="New York"+"Alabama"+"California"

  If you use the Pn syntax, then you do not need to enclose a value that contains a space within double quotation marks.

• To include a user or system field in a filter parameter, place your cursor in the Parameters field at the position where you want to add the parameter, and then select the field that you want to include from the User and System Fields list.

  For information about the user and system fields that you can use in the parameters, see User and System Fields.

• (Web applets for record-type Detail pages only, and Web links) To include a field from the record type in a filter parameter, place your cursor in the Parameters field at the position where you want to add the field, and then select the field from the record type Fields list, where record type is the name of the record type for which you are creating the applet.

  For example, if you select the Row Id field from the record type Fields list, then %%%Row_Id%%% is inserted. At run time, %%%Row_Id%%% is replaced with the row ID of the current record.

NOTE: The URL for a report or dashboard is generated at run time. The length of the URL for the report or dashboard varies, depending on the values that are passed to the URL for the filters at run time. Each browser has a maximum URL length. If the URL for a report or dashboard exceeds this length, then users might see indeterminate behavior on the browser when they attempt to view that report or dashboard.

NOTE: You can specify parameters for a report, a dashboard, or a dashboard page in a Send Email action on a scheduled event for Analytics in the same way that you specify the parameters for an embedded report or dashboard in a Web applet, tab, or link. However, you cannot select fields to specify as parameter values in a Send Email action. For information about setting up scheduled events for Analytics, see Creating Scheduled Events for Analytics.