5
Controlling User Access

The celebrated openness of the Internet brings with it concerns about controlling who has access to what confidential company information. Oracle9iAS Portal provides a number of security features available to Oracle9iAS Reports Services that enable you to ensure that the appropriate users are getting important data in a secure fashion. With Oracle9iAS Portal security features in place, your users see only the data they're supposed to see.

Use Portal to control:

Who has access to each report
When a report can be run
Which servers and printers can be used to run a report
Which report parameters a user can edit with what range of values

This chapter describes how to use Oracle9iAS Reports Services security and the out-of-the-box security implementation provided with Oracle9iAS Portal to control user access to your Reports environment. It includes the following sections:

Before you can set up security controls, both Oracle9iAS Portal and Oracle9iAS Reports Services must be installed and configured. See Chapter 3, "Configuring Oracle9iAS Reports Services" for information on configuring Reports Services. See the Oracle9iAS Portal documentation for information on configuring Oracle Portal. See also the Oracle9iAS Install Guide, for information on installing both components. You'll find information about Oracle9iAS and Oracle9iAS Portal on the Oracle9iAS documentation CD and on the Oracle Technology Network, http://otn.oracle.com.

5.1 Introduction to Oracle9iAS Portal

Oracle9iAS Portal is a browser-based, data publishing and developing solution that offers Web-based tools for publishing information on the Web and building Web-based, data-driven applications.

Oracle9iAS Portal is tightly integrated with Oracle9iAS Reports Services to create a robust and secure data publishing environment. Oracle9iAS Portal provides easy-to-use wizards for setting up Oracle9iAS Reports Services security. These include wizards for defining user access to reports, Oracle9iAS Reports Servers, printers, output formats, and report parameters.

Once you define access control information, it's stored in the Oracle9iAS Portal repository. As an Oracle9iAS Portal user, you can then, optionally, publish registered RDFs and JSPs to an Oracle9iAS Portal page. As with all Oracle9iAS Portal functionality, using Portal to deliver your reports is not required. You can deliver reports through command lines, as you may always have, and still benefit from the access control features available to you through Oracle9iAS Portal.

Access to Oracle9iAS Reports Services' security features is not dependent on whether you also use Portal to publish report links or report content. Even if you don't publish via Portal, you can still take advantage of the Oracle9iAS Reports Services' security features available in Oracle9iAS Portal to control user access to all of your reports.

When you expose a report as a portlet through Oracle9iAS Portal, Oracle9iAS Reports Services leverages the Oracle Single Sign-on feature. Oracle Single Sign-on eliminates the need for users to enter multiple logins, first to the portal then to each of the applications exposed through portlets within the portal. With Single Sign-On, when you log in, Oracle9iAS Portal automatically logs you into all registered portlet providers and subsystems.

Refer to the Oracle9iAS Security Guide for more information about Single Sign-on. You'll find this and other related documentation on the Oracle Technology Network, http://otn.oracle.com.

5.2 Defining Portal-Based Security in the Server Configuration File

If you plan to use the security features, you must set up the security element in your Reports Server configuration file: <server_name>.conf. You'll find this file in the following directory path on both UNIX and Windows platforms:

ORACLE_HOME\reports\conf\<server_name>.conf

For the out-of-the-box Portal security implementation, the Reports Server configuration file's security element requires a property that includes a valid Portal username, password, and database connect string SID. The Reports Server uses this information to connect the server to Portal and retrieve the access control parameters you set there. The server's connection to Portal is performed in the background and does not present any displayed components. A user can run a report that has access controls without being aware that those controls were specified in and served up via Oracle9iAS Portal.

In the Reports Server configuration file, your security configuration entry might look like this:

<security id="rwSec" class="oracle.reports.server.RWSecurity">
   <property name="securityUserid" value="portal_id/portal_password@portal_schema" confidential="yes" encrypted="no"/>
</security>

Note:

If you implement your own security interface, you need to implement in Java. Refer to the Oracle Technology Network (http://otn.oracle.com/products/reports/) for more information on the Oracle9iAS Reports Services APIs .

Valid attributes of the security element are described in Table 5-1.

Table 5-1 Attributes of the security element

Attribute	Valid values	Precondition or default	Description
id	string	required	A keyword, unique within a given configuration XML file, that identifies a particular security element. This can be a text string or a number, for example `id="rwSec"`.
class	see Description	required	A fully qualified Java class that implements the Reports Server Security Java interface (oracle.reports.server.Security). The default value is oracle.reports.server.RWSecurity, which relies on security features available through Oracle Portal (included with Oracle9iAS).

Additionally, the security element in this example uses the name/value pair: securityUserid/portal_id/portal_password@portal_schema. securityUserid is the name of the property, and portal_id/portal_password@portal_schema describes a valid, administrator-level user id, password, and SID for entry into Portal. This example also includes the attributes confidential and encrypted: confidential="yes" indicates that the values within this element should be encrypted; encrypted="no" indicates that the values are not yet encrypted. The next time the Reports Server starts, it will automatically encrypt the values and reset encrypted to yes.

The security configuration element is explained in detail in Section 3.2.1.5, "security" in Chapter 3.

5.3 Creating Reports Users and Named Groups in Oracle9iAS Portal

If you use the security features in Oracle Portal to control access to your reports, you must register all of your Reports users in the Oracle Internet Directory (OID) and assign security privileges to all of them through Oracle9iAS Portal.

Note:

If you have a large user population already entered into an LDAP-compatible directory, you can use Oracle Internet Directory (OID) features to synchronize the directories and save yourself the effort of entering your users individually. You'll find information about OID's Directory Integration Server in the OID Administrator's Guide.

In Portal, security privileges can be granted to individual users and to named groups of users. Named groups are useful for streamlining the process of granting access privileges. You can assign a set of access privileges to a named group, and grant the entire set of privileges to an individual simply by adding that person to the group.

The next sections provide overview information on how to create users and groups in Oracle9iAS Portal. They include:

5.3.1 Default Reports-Related Groups

When you install Oracle9iAS Portal, Reports-related groups are created for you automatically. These include the following groups:

Every person who will access your reports should belong to one of these groups. Each of these groups comes with a set of access privileges, which you may customize if you wish. If users try to run reports without being a member of one of these groups, by default, they are assigned the privileges of a basic user. The groups and their privileges are described in the following subsections.

5.3.1.1 RW_BASIC_USER

Basic users have EXECUTE privileges. They can run a report and see the result. Should the security check fail, they see less detailed error messages than the other Reports user groups see, such as:

Security Check Error

5.3.1.2 RW_POWER_USER

In addition to the privileges of the RW_BASIC_USER group, the RW_POWER_USER group sees error messages that are more detailed than those displayed to basic users. For example, if they are not permitted to run to HTML, but they try anyway, they might get the message:

Cannot run report to HTML

This is more detailed than the message an RW_BASIC_USER would receive for the same error.

5.3.1.3 RW_DEVELOPER

In addition to the privileges of the RW_POWER_USER and RW_BASIC_USER groups, the RW_DEVELOPER group can run commands, such as SHOWENV and SHOWMAP, which show the system environment. You would assign a developer who needs to do testing and to retrieve detailed error messages to this group.

5.3.1.4 RW_ADMINISTRATOR

Users assigned to this group have MANAGE privileges. They can CREATE, UPDATE, and DELETE the registered report definition files, servers, and printer objects in Oracle9iAS Portal. In addition to all the links activated for the developer user, administrators can navigate to the Access tab on the Component Management Page, accessible in Oracle9iAS Portal. This is where the administrator can specify who will have access to this report. People with administrator privileges can assign security privileges for other people and receive full error messages from Oracle9iAS Reports Services.

These users also have access to the administrator's functionality in Oracle9iAS Reports Queue Manager, which means they can manage the server queue, including rescheduling, deleting, reordering jobs in the server, and shutting down a server.

Refer to the Oracle9iAS Security Guide for information on creating and managing a user.

5.3.2 Creating Users and Groups

Oracle9iAS Portal uses the Delegated Administration Service (DAS) interface to the Oracle Internet Directory (OID) to register users for access to Portal. You can enter the DAS interface through Portal to create new users. The creation of new users and groups is discussed in the Oracle9iAS Security Guide, available on the Oracle9iAS documentation CD. Look for the chapter entitled, "Configuring Oracle9iAS Portal Security."

5.4 Setting Up Access Controls

Before you begin, you must have a sufficient level of privileges in Oracle9iAS Portal in order to access the portlets and complete the tasks required for setting access controls. You will find information about joining privileged groups in the Oracle9iAS Security Guide, available on the Oracle9iAS documentation CD. Look for the chapter entitled, "Configuring Oracle9iAS Portal Security."

Once you have a sufficient level of privileges, you can use the information in the following sections to learn about:

5.4.1 Creating an Availability Calendar

Defining availability calendars is an optional step that allows you to further restrict access to reports, servers, and printers by specifying when they can and cannot be accessed. Availability calendars are not necessary if the reports, the Reports Servers, and printers are always available for processing.

This section provides information on:

You can associate only one availability calendar with a report, a Reports Server, or a printer. If your production environment requires more than one availability rule, then you can combine availability calendars.

5.4.1.1 Creating a Simple Availability Calendar

A simple availability calendar defines a single availability rule (for example, Sunday through Saturday from 12:00 a.m. to 10:00 p.m.).

To create a simple availability calendar:

Log in as an administrator to Oracle9iAS Portal.
Click the Builder button at top of the Portal main page.
On the resulting page, click the Administer tab.
Under the Oracle Reports Security portlet, click Create Reports Simple Calendar Access.
Specify an internal name, display name, and Portal DB Provider for the calendar:
- In the Name field, enter a unique name that will identify the availability calendar internally in Portal, for example, MY_CALENDAR. This name must follow the Portal rules for a valid component name, specified in the Portal online help.
- In the Display Name field, enter the name you want to display for this availability calendar when it is exposed through Portal. Unlike the internal name, the display name can have spaces in it.
- Select a Portal DB Provider from the provider list of values. All components added to or created in Portal must belong to a Portal DB Provider. This list contains the names of only those providers with which you have privileges to build components.
  
  Note:
  For information on creating a Portal DB Provider, see the Oracle9iAS Portal online help.
Click the Next button.
Optionally, enter a description of the calendar under Description.
Click the Next button.
On the Date/Time Availability page, define the parameters for the calendar:

Under Duration, specify the length of time that comprises a unit of duration (or duration period). For example, if you plan to set this calendar up to allow report access between 9:00 AM to 5:00 PM on a given day, then both Start and End would be the same month, day, and year, but the hour and minute setting for Start would be 9:00 AM and for End would be 5:00 PM. In this example, the duration of availability of a report on a given day is from 9:00 AM to 5:00 PM.

Under Repeat, specify how frequently the duration period is repeated:
- Occurs only once means the duration period does not repeat, and associated components are no longer available when the period expires. For example, if you select Occurs only once and set a duration period of one year, then the associated components cease to be available after one year.
- Yearly means the duration period restarts each year. If you select Yearly and have the same start and end date in your Duration setting, but your Start hour is set to 9:00 AM and your End hour is set to 5:00 PM, then the Reports components associated with this availability calendar will be available one day a year between 9:00 and 5:00.
- Monthly means the duration period restarts each month between the Start and End dates specified under Duration. If you select Monthly and have the same date and year in both Start and End--July 25, 2001--but set the Start hour for 9:00 AM and the End hour for 5 PM, then the associated components will be available between 9:00 AM and 5:00 PM on the 25th of each month.
- The by Date/Day setting applies only to Monthly. With by Date/Day, you specify whether the duration period is set by the particular date (e.g., always on the 25th through the 29th of the month) or by the particular day(s) (e.g., always on Monday through Friday--which happen this month to fall on the 25th through the 29th).
- Weekly means the duration period restarts on a weekly basis between the days specified under Duration.
- Daily means the duration period restarts each day between the hours specified under Duration.
- Frequency fills in the missing value for the phrase: Repeat every n (years, months, weeks, days--depending on what you selected under Repeat). For example, if you set the duration period to repeat weekly, then set Frequency to 2, the duration period restarts every two weeks, or every other week.
- Optionally, check Repeat Until and assign a termination date/time for the calendar. Availability for all associated Reports components ends on the Repeat Until date/time.
  
  Note that no validation is run on your calendar. If the duration period exceeds the repetition setting, no error message will be generated. For example, if you set the duration period for 10 days and the repetition for weekly, the periods will overlap, but you will not be notified of the overlap.
Click the Next button.
On the Summary page, click the Show Calendar button to preview your availability calendar. If you wish to change some settings, click the Previous button and make your changes.
On the Summary page, click the Finish button to complete the availability calendar.
Click the Close button to return to the Oracle Reports Security page.

5.4.1.2 Creating a Combined Availability Calendar

A combined availability calendar combines two or more availability calendars into a single availability calendar. This is useful when you want to set up an availability period, then exclude specific days, such as holidays, from that period.

When you combine calendars, you can indicate that all the days on one of them be excluded from all the days on the other. For example, one calendar could describe availability Monday through Friday; another could describe availability only on Wednesday. You could combine these, excluding the Wednesday calendar, so that the combined calendar describes availability Monday, Tuesday, Thursday, Friday.

Conceivably, you could create a simple calendar that covers the weekdays of an entire year, then multiple additional simple calendars, where one excludes New Years, another excludes a second holiday, another excludes a third, and so on. You could combine all these calendars, excluding all the holiday calendars, so that components were available only on the days your company is open for business, between certain times of day, throughout the year.

To combine availability calendars:

Log in as an administrator to Oracle9iAS Portal.
Click the Builder button at the top of the Portal main page.
On the resulting page, click the Administer tab.
Under the Oracle Reports Security portlet, click Create Reports Combined Calendar Access.
Specify an internal name, display name, and Portal DB Provider for the calendar:
- In the Name field, enter a unique name that will identify the combined availability calendar internally in Oracle9iAS Portal, for example, MY_COMBINED_CALENDAR. This name must follow the Portal rules for a valid component name set out in the Portal online help.
- In the Display Name field, enter the name you want to display for this combined availability calendar when it is exposed through Portal. Unlike the internal name, the display name can have spaces in it.
- Select a Portal DB Provider from the provider list of values. All components that you add to or create in Portal must belong to a Portal DB Provider. This list contains the names of only those providers with which you have privileges to build components.
  
  Note:
  For information on creating a Portal DB Provider, see the Oracle9iAS Portal online help.
Click the Next button.
Optionally, enter a description of the calendar under Description.
Click the Next button.
On the Selection page, highlight the calendars on the Availability Calendars list that you want to combine.

On Windows, control-click to select multiple calendars.

On UNIX, click each calendar you want to select.

This page lists the availability calendars that have been defined for the same Portal DB Provider under which you are creating this combined availability calendar.
Click the right arrow to move the selected calendars to the Selected Availability Calendars list.
Click the Next button.
On the Exclude page, highlight the calendar(s) on the Availability Calendars list whose dates you want to exclude.

On Windows, control-click to select multiple calendars.

On UNIX, click each calendar you want to select.

These are the calendars with dates on which you wish to withdraw availability.
Click the right arrow to move the selected calendars to the Excluded Availability Calendars list.
Click the Next button.
On the Summary page, click the Show Calendar button to preview your calendar.

If your exclusion isn't showing up, select a different view. For example, instead of the monthly view, select the weekly.

If you want to change the combination, close the calendar and click the Previous button one or more times to return to the desired page.
Click Finish to complete creation of the combined calendar.

You can combine this calendar with other calendars or apply it "as is" to registered Reports components.

5.4.2 Registering a Printer

It is not required that you register a printer within the security framework of Oracle9iAS Portal. You can run a report on any printer as long as it is available to the Reports Server. However, you might want to confine Oracle9iAS Portal users to a subset of those printers, constrain the use of a printer for certain periods of time, or identify a particular printer to be used for printing output of certain reports.

Printer registration with Portal is meaningful for reports that you run through Portal as well as those you run through a stand-alone URL.

Once printers are registered within Oracle9iAS Portal, you can associate them with an Oracle9iAS Reports Server. Many printers can be registered. However, only printers associated with particular Oracle9iAS Reports Servers are available to print when you register a report with Portal and choose those Reports Servers.

You can choose to restrict even further the registered subset of printers that a registered report can be sent to. For example, an Oracle9iAS Reports Server might be connected to the printer in the office of the CEO, but its selection should not be available to employees running the general ledger report, unless it is the CEO who is running the report. A subset of printers can be listed to the Oracle9iAS Portal user running a report request to select where output should be sent.

To register a printer:

Log in as an administrator to Oracle9iAS Portal.
Click the Builder button at the top of the Portal main page.
On the resulting page, click the Administer tab.
Under the Oracle Reports Security portlet, click Oracle Reports Security Settings.
Under the Reports Printer Access portlet, click Create Reports Printer Access.
On the resulting page, the Name, Display Name, and Portal DB Provider fields are filled in with default values. Change these to your desired values:
- In the Name field, enter a unique name that will identify the printer internally in Oracle9iAS Portal, for example, MY_PRINTER. This name must follow the Portal rules for a valid component name set forth in the Portal online help.
- In the Display Name field, enter the name you want to display for this printer when it is exposed to your users through Portal. Unlike the internal name, the display name can have spaces in it.
- From the Portal DB Provider list of values, choose the Portal DB Provider that will own the printer. All components you add to or create in Portal must belong to a Portal DB Provider. This list contains the names of only those providers with which you have privileges to build components.
Click the Next button.
On the resulting page, fill in desired values:
- In the OS Printer Name field, enter the operating system printer name, for example:
```
UNIX: <printer_name>

Windows: \\<printer_server>\<printer_name> (for a remote printer)

<printer_name> (for a local printer)
```
  This printer must be available to the Reports Server.
  
  Note:
  Printer availability is set via the operating system on the Report Server's host machine.
- Optionally, in the Description field, type a description of the printer.
Click the Next button.
Optionally, choose an availability calendar to restrict the days and times the printer can be used. You'll find more information about availability calendars in Creating an Availability Calendar.
Click the Finish button.

The resulting page summarizes your Portal settings for this printer. On this page, you can edit your settings, get detailed registration information about the printer, or delete it from Portal altogether.
Click the Close button to close this page and return to Portal's Oracle Reports Security page.

You have completed registering a printer with Portal. This registration is meaningful for reports that are run through Portal as well as those run outside of Portal.

5.4.3 Registering a Reports Server

Before you can define access controls for the Reports Server, you must register your server within Portal (i.e., this is required). Registration provides Portal with the information it needs to identify and locate all available Reports Servers. This becomes particularly important when you register individual reports; during this process you are required to choose from a list of Reports Servers, and servers must be registered to appear on this list.

This section describes how to register Reports Servers in Oracle9iAS Portal.

To register a Reports Server:

Log in as an administrator to Oracle9iAS Portal.
Click the Builder button at the top of the Portal main page.
On the resulting page, click the Administer tab.
Under the Oracle Reports Security portlet, click Oracle Reports Security Settings.
Click Create Reports Server Access.
On the resulting page, the Name, Display Name, and Portal DB Provider fields are filled in with default values. Change these to your desired values:
- In the Name field, enter a unique name that will identify the Reports Server internally in Oracle9iAS Portal, for example, MY_REPORTS_SERVER. This name must follow the Portal rules for a valid component name set forth in the Portal online help.
- In the Display Name field, enter the name you want to display for this server when it is exposed to your users through Portal. Unlike the internal name, the display name can have spaces in it.
- From the Portal DB Provider list of values, choose the Portal DB Provider that will own the server. All components you add to or create in Portal must belong to a Portal DB Provider. This list contains the names of only those providers with which you have privileges to build components.
Click the Next button.
On the Server Definition page:
- In the Reports Server Name field, enter the name of the Reports Server. This is the unique name you gave the server when you installed it, provided you haven't changed that name. (If so, enter the new name.)
- In the Description field, optionally, enter a description of this Reports Server.
- In the Oracle Reports Web Gateway URL for JSP reports field, enter the URL that points to the location of your Java Server Page (JSP) files. For example:
```
http://<your_web_server>.<domain>/<virtual_path_to_JSPs>/
```
  Note:
  For information on specifying the virtual path, see Chapter 3, "Configuring Oracle9iAS Reports Services".
- In the Oracle Reports Web Gateway URL for RDF reports field, Enter the URL that points to the location of the Reports Servlet. For example:
```
http://<your_web_server>.<domain>/<virtual_path_to_rwservlet>/rwservlet
```
  Note:
  For information on specifying the virtual path, see Chapter 3, "Configuring Oracle9iAS Reports Services".
- If you want only the report definition files that are registered in Portal to run when requested, check the Run Only Registered Report Definition Files check box.
  
  Leave this box unchecked if you want this Reports Server to accept any report definition file, including those not registered in Portal, as long as the user who submits the report request has access privileges to this Reports Server.
- From the Printers list, select the printer(s) that you want to make available to this Reports Server. Multiple selections are possible:
  
  On Windows, control-click the printers you want to select.
  
  On UNIX, click the printers you want to select.
Click the Next button.
On the Destination Types page, enter custom destination types for this Reports Server. Note that default destinations that come with your Oracle9iAS installation need no further configuration in Portal.

Note:
For information on custom destination types, see Chapter 4, "Configuring Destinations for Oracle9iAS Reports Services".
Click the Next button.
On the Availability Calendar page, optionally choose an availability calendar to control the days and times this Reports Server is available to accept report requests.
Click the Finish button.
Click the Close button.

This returns you to the Oracle Reports Security Setting page.

You have registered an Oracle9iAS Reports Server. Now you can register a report.

5.4.4 Registering a Report

Registering a report is a required step that allows you to define who can run a report, when a report is available to run, which server(s) can be used to process report requests, how a report is delivered, and the printer(s) to which a report can be sent.

In addition to using registration to designate which users have access to a report, you can also specify, via a Portal parameter form, how users are to interact with the report.

In the Reports Builder, users create user parameters. Then, in Portal, users specify the names of these parameters, enabling end users to select or enter values for these parameters when they run the report. At runtime, the Reports Server disregards parameters you set in Portal that were not also defined in the Reports Builder at design time.

Use the parameter settings available through Portal to duplicate or create a subset of those parameters defined in the Reports Builder at design time. This way you get parameter coverage when you run the report via Oracle9iAS Portal.

Registering a report within Oracle9iAS Portal creates an Oracle9iAS Portal component that can be deployed as a portlet through Portal. We recommend that you register only one instance of a report file in Portal. If you define multiple Portal Reports objects for one report, all are given security checks at runtime. If any of them fail the security check, then all fail it, and the job will not run.

To register a report:

Log in as an administrator to Oracle9iAS Portal.
Click the Builder button at the top of the Portal main page.
On the resulting page, click the Administer tab.
Under the Oracle Reports Security portlet, click Oracle Reports Security Settings.
Under the Reports Definition File Access portlet, click Create Reports Definition File Access.
The Name, Display Name, and Portal DB Provider fields are filled in with default values. Change these to your desired values:
- In the Name field, enter a unique name that will identify the report internally in Portal, for example, MY_REPORT. This name must follow the Portal rules for a valid component name set forth in the Portal online help.
- In the Display Name field, enter the name you want to display for this report when it is exposed through Portal. Unlike the internal name, the display name can have spaces in it.
- From the Portal DB Provider list of values, choose the Portal DB Provider that will own the report. All components added to or created in Portal must belong to a Portal DB Provider. This list contains the names of only those providers with which you have privileges to build components.
Click the Next button.
Enter or select information as follows:
- From the Reports Servers list of values, select the Reports Server(s) to be available to run this report.
  
  To select multiple servers:
  
  On Windows, control-click each server.
  
  On UNIX, click each server.
- In the Oracle Reports File Name field, enter the name you gave the report in the Builder, including its extension.
  
  The report definition file can be an .rdf, .jsp, or .xml file. If the path to this file is included in your REPORTS_PATH environment variable, do not enter it here. If the path is not included in REPORTS_PATH, include it here along with the filename. Do this for all report definition files except those you will run as stand-alone JSPs.
- Optionally, type a description of this report in the Description field.
- In the Execute field, choose between via servlet and as JSP.
  
  Choose via servlet if you plan to run the report via the Reports Servlet. Choose as JSP if you will run a JSP report stand-alone, without going through the Reports Servlet.
  
  The selection you make here will affect the choices that are available on the next wizard page.
Click the Next button.
On the Required Parameters page set required runtime information. These settings are only applicable if running through the Reports Servlet. At runtime, anywhere you have indicated multiple selections, using control-click, a list of values will be offered to your users, from which they can set their own runtime information:
- Types specifies the destination types acceptable for this report. Choose among Cache, File, Mail, OraclePortal, Printer, or custom destination types. If the server you associate with this report supports custom destination types, which you indicated when you registered the Reports Server in Portal, the types you indicated will display on this list.
- Formats defines the acceptable output format(s) for this report. Choose among HTML, HTMLCSS, PDF, XML, RTF, Delimited, PostScript, and Character
- Printers specifies the registered printer(s) to which this report can be sent. The printers that appear on this list are determined by those you chose when you set up access to the Reports Server(s) you are associating with this report. All registered printers are listed. When users choose a Reports Server on the runtime parameter form, only those printers that are associated with the selected Reports Server and that are accessible to those users are listed.
- Parameter Form Template specifies the template that will define the look and feel of the Portal parameter form from which you will run the report. This value is used only when the report is exposed through the Portal. Choose a template from the list of values. Click Preview Template to see what the selected template looks like.
  
  Note:
  For information about adding your own templates to this list, see the Oracle9iAS Portal online help.
Click the Next button.
On the Optional Parameters page define limits for the report's existing parameters.
- Name is the name of the system or user parameter on which you wish to restrict the values available to users, for example, SALES_REGION or COPIES.
- Display Name is the name used to identify the parameter on the runtime parameter form.
- LOV is the name of a predefined list of values to be included in the parameter form. The list must already exist. For information on creating a list of values, see the Portal online help.
- Low Value is the lowest value you wish to set for a range of values.
- High Value is the highest value you wish to set for a range of values.
- Click More Parameters if you wish to add more rows for additional parameters and values.
Click the Next button.
Optionally, enter the name of the availability calendar (or choose from a list of calendars).

Use the availability calendar to limit the days and times this report can be run. For more information, see Section 5.4.1, "Creating an Availability Calendar".
Click the Next button.
Optionally, enter a validation trigger to create a programmatic restriction.

Use validation triggers to create conditional restrictions that cannot be defined on either the Required Parameters page or the Optional Parameters page. Validation triggers are PL/SQL functions.

The function that you specify as a validation trigger must return a boolean value (TRUE or FALSE). If the function returns TRUE, the job is run. If the function returns FALSE, an error message is displayed and the job is not run.

Click Finish to close the wizard and complete report registration.

The resulting page summarizes your registration information and provides the opportunity to perform additional actions on your report.

Click Customize to view the report's runtime parameter form.

Table 5-2 summarizes the options available on this page.

Table 5-2 Options on the runtime parameter form

Option	Description
Run Report	Click to run this report with the specified parameter values.
Save Parameters	Click to save the parameter value selections.
Server	Choose the Oracle Reports Server that you want to receive this report request. Only the servers you chose from the Report Name and Servers page are displayed in this list box.
Printer	Choose the printer that you want to print your report output. Only the printers you chose from the Required Parameters page are displayed in this list box.
Destype	Choose the destination type. Only the destination types you chose from the Required Parameters page are displayed in this list box.
Desformat	Choose the destination format. Only the destination formats you chose from the Required Parameters page are displayed in this list box.
Desname	Enter the name of the output file when Destype is FILE, or enter the e-mail addresses when the Destype is MAIL. Separate multiple addresses with commas. The destination name is required when you choose FILE or MAIL as the Destype.
SSOCONN	Enter one or more SSO connection strings. Separate multiple strings with a comma (but no spaces).
Visible to user	Check each parameter that you want to make available in the runtime parameter form when users run this report request. If the box in not checked, then the parameter is not displayed to users.
CGI/Servlet Command Key	Optionally, enter the key from the cgicmd.dat file that identifies the command line to run for this report.
Additional User Parameters	Use this field to enter additional user parameters. For example, you can use this field to enter the path and name of the distribution XML file that defines how this report should be distributed. Use the same syntax you would use to specify these values in a command line request or within the cgicmd.dat file. If you wish to enter multiple additional parameters, simply separate each entry with a space. For more information about the distribution XML file, see Chapter 9, "Creating Advanced Distributions".

5 Controlling User Access