11
Deploying Reports in OracleAS Portal

This chapter describes how to use OracleAS Portal to deploy your Oracle Application Server Reports Services reports. It includes the following sections:

• Creating Reports Users and Named Groups in OracleAS Portal

• Registering Oracle Reports Components in OracleAS Portal

Before you deploy reports, both OracleAS Portal and Oracle Application Server Reports Services must be installed and configured.

See also: The following resources for further information: Chapter 3, "Configuring OracleAS Reports Services" for information on configuring Oracle Application Server Reports Services the Oracle Application Server Portal Configuration Guide for information on configuring OracleAS Portal the Oracle Application Server 10g Installation Guide for information on installing both components the Oracle Application Server documentation CD the Oracle Technology Network, (http://otn.oracle.com)

11.1 Creating Reports Users and Named Groups in OracleAS Portal

If you use the security features in OracleAS 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 OracleAS 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 OracleAS 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.

Note: When you use features like OracleAS Portal Security, Portal Destination, and Job Status Repository, the JDBC database connections made by Oracle Application Server Reports Services may override the initial NLS_LANG setting. This change may in turn affect the behavior of the running report, such as bidirectional output in PDF. On UNIX platforms, you can work around this issue by setting the NLS_LANG explicitly in report.sh. You can also use the new environment switching functionality to dynamically set the environment for reports. Refer to Dynamic Environment Switching, for more information.

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

• Default Reports-related Groups

• Creating Users and Groups

11.1.1 Default Reports-related Groups

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

• RW_BASIC_USER

• RW_POWER_USER

• RW_DEVELOPER

• RW_ADMINISTRATOR

You need to assign appropriate privileges to these groups to enable group members to perform any desired functions on reports through OracleAS Portal. For example, for each report object that you want members of a group (e.g., RW_BASIC_USER) to be able to run, you have to grant the Execute privilege to that group from the Access tab of the report object. Similarly, if you want members of a group (e.g., RW_ADMINISTRATOR) to be able manage Reports Servers, printers, and reports, you have to grant the Manage privilege to that group from the Access tab of those objects.

While you can assign object privileges to individual users, we recommend that every person who will access your reports belong to one of these groups or a group that you create yourself. 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.

11.1.1.1 RW_BASIC_USER

Should the security check fail, the users in RW_BASIC_USER see less detailed error messages than the users in other Oracle Reports groups, such as:

Security Check Error

Typically, you will want to assign this group minimal privileges. For example, you probably will want to give RW_BASIC_USER the privilege to execute reports and no more.

11.1.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.

11.1.1.3 RW_DEVELOPER

In addition to the privileges of the RW_POWER_USER groups, the RW_DEVELOPER group can run Web commands, such as SHOWENV and SHOWMAP, which show the system environment.

Typically, you would assign privileges to this group needed by a developer who is testing reports. Depending upon your installation, you might even assign them limited administrative privileges.

11.1.1.4 RW_ADMINISTRATOR

In addition to the privileges of RW_DEVELOPER, these users also have access to the administrator's functionality in the Oracle Reports Queue Manager, which means they can manage the server queue, including rescheduling, deleting, reordering jobs in the server, and shutting down a server. RW_ADMINISTRATOR also has the privilege to run Web commands through rwservlet.

Typically, you will want to assign to this group some (but probably not all) of the same privileges assigned to the PORTAL_ADMINISTRATORS group.

Note: Initially, only members of the PORTAL_ADMINISTRATORS group have MANAGE privileges for Oracle Reports objects. They can CREATE, UPDATE, and DELETE the registered report definition files, servers, and printer objects in OracleAS 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 OracleAS 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 Oracle Application Server Reports Services.

11.1.2 Creating Users and Groups

OracleAS 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 Oracle Application Server Portal Configuration Guide available on the Oracle Application Server documentation CD.

When you create groups, you need to assign appropriate privileges to them to enable group members to perform any desired functions on reports through OracleAS Portal. For example, for each report object that you want members of a group (e.g., RW_BASIC_USER) to be able to run, you have to grant the Execute privilege to that group from the Access tab of the report object. Similarly, if you want members of a group (e.g., RW_ADMINISTRATOR) to be able manage Reports Servers, printers, calendars, and reports, you have to grant the Manage privilege to that group from the Access tab of those objects.

Ideally, you should provide a user with the necessary privileges on objects by assigning them to a group that has appropriate privileges for their role. For example, if you are creating a user who needs to be able to run but not manage reports, you could assign her to RW_BASIC_USER. If need be, you may assign object privileges to individual users (e.g., JSMITH) rather than groups, but this approach is more difficult and time consuming to manage.

11.2 Registering Oracle Reports Components in OracleAS Portal

Before you begin, you must have a sufficient level of privileges in OracleAS Portal to access the portlets and complete the tasks required for setting access controls. In order to manage reports in OracleAS Portal, you must belong to both the PORTAL_ADMINISTRATORS and RW_ADMINISTRATOR groups. If you only belong to RW_ADMINISTRATOR, you will encounter errors when you attempt to create report objects.

For more information about joining privilege groups in OracleAS Portal, refer to the Oracle Application Server Portal Configuration Guide.

See Also: Running Report Requests For more information on running reports in OracleAS Portal.

This section outlines the necessary steps to go about:

• Creating an Availability Calendar

• Registering a Printer

• Registering a Reports Server

• Registering a Report

11.2.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:

• Creating a Simple Availability Calendar

• Creating a Combined Availability Calendar

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.

11.2.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:

1. Log in as an administrator to OracleAS Portal.

2. Navigate to the Builder page.

3. Click the Administer tab.

4. Click the Oracle Reports Security Settings link in the Oracle Reports Security portlet.

5. Click the Create Reports Simple Calendar Access link in the Reports Calendar Access portlet on the Oracle Reports Security page.

6. On the resulting page, the Name (internal name) and Portal DB Provider fields contain default values. To include custom values:
   • Enter a unique name in the Name field that will identify the availability calendar internally in OracleAS Portal, for example, MY_CALENDAR. This name must follow the OracleAS Portal rules for a valid component name, i.e.,:
     • It must be no more than 30 characters

     • It must contain only alphanumeric characters (no spaces or special characters allowed).

     • The first character must be a letter (not a number).

   • In the Display Name field, enter the name you want to display for this availability calendar when it is exposed through OracleAS 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 OracleAS 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 OracleAS Portal online help.

7. Click Next.

8. Optionally, enter a description of the calendar under Description.

9. Click Next.

10. 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 from 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: 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.

11. Click Next.

12. 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.

13. On the Summary page, click Finish to complete the availability calendar.

    The resulting page summarizes your settings for this calendar. On this page, you can edit your settings, get detailed information about the calendar, or delete it.

14. Click Close to close this page and return to OracleAS Portal's Oracle Reports Security page.

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

11.2.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:

1. Log in as an administrator to OracleAS Portal.

2. Navigate to the Builder page.

3. Click the Administer tab.

4. Click the Oracle Reports Security Settings link in the Oracle Reports Security portlet.

5. Click the Create Reports Combined Calendar Access link in the Reports Calendar Access portlet.

6. Specify an internal name, display name, and Portal DB Provider for the calendar:
   • Enter a unique name in the Name field that will identify the combined availability calendar internally in OracleAS Portal, for example, MY_COMBINED_CALENDAR. This name must follow the OracleAS Portal rules for a valid component name, i.e.,:
     • It must be no more than 30 characters

     • It must contain only alphanumeric characters (no spaces or special characters allowed).

     • The first character must be a letter (not a number).

   • Enter the name you want to display for this combined availability calendar in the Display Name field. The Display Name is the name that is exposed to your users through OracleAS Portal.

     Note: The Display Name, unlike the internal 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 OracleAS Portal online help.

7. Click Next.

8. (Optional) Enter a description of the Availability Calendar in the Description field.

9. Click Next.

10. On the Selection page, highlight the calendars on the Availability Calendars list that you want to combine. The calendars are listed by their internal names, not their display names. Use control-click (Windows) or click (UNIX) to select multiple calendars.

    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.

11. Click the right arrow to move the selected calendars to the Selected Availability Calendars list.

12. Click Next.

13. On the Exclude page, highlight the calendar(s) on the Availability Calendars list whose dates you want to exclude. Use control-click (Windows) or click (UNIX) to select multiple calendars.

    These are the calendars with dates on which you wish to withdraw availability.

14. Click the right arrow to move the selected calendars to the Excluded Availability Calendars list.

15. Click Next.

16. 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.

17. Click Finish to complete creation of the combined calendar.

    The resulting page summarizes your settings for this calendar. On this page, you can edit your settings, get detailed information about the calendar, or delete it.

    See Also: The Manage Portlet For more information on the fields and descriptions listed in the Manage portlet, i.e., Develop, Manage, and Access tabs.

18. Click Close to close this page and return to OracleAS Portal's Oracle Reports Security page.

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

11.2.2 Registering a Printer

It is not required that you register a printer within the security framework of OracleAS 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 OracleAS 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 OracleAS Portal is meaningful for reports that you run through OracleAS Portal as well as those you run through a stand-alone URL.

Once printers are registered within OracleAS Portal, you can associate them with a Reports Server. Many printers can be registered. However, only printers associated with particular Reports Servers are available to print when you register a report with OracleAS 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 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 OracleAS Portal user running a report request to select where output should be sent.

Table 11-1 Sample Values

Property	Sample Value
Name (internal name)	myrep_printer
Display Name	My Reports Printer
Portal DB Provider	PORTAL_APP
OS Printer Name	\\mydomain\printer1
Availability Calendar	COMCAL

To register a printer:

1. Log in as an administrator to OracleAS Portal.

2. Navigate to the Builder page.

3. Click the Administer tab.

4. Click the Oracle Reports Security Settings link in the Oracle Reports Security portlet. The Oracle Reports Security portlet enables you to use the security features in OracleAS Portal at the time of defining access to the server, printer, calendar, and reports definition file.

5. Click the Create Reports Printer Access link in the Reports Printer Access portlet.

6. On the resulting page, the Name (internal name) and Portal DB Provider fields contain default values. To include custom values:
   • Enter a unique name in the Name field that will identify the printer internally in OracleAS Portal, for example, MY_PRINTER. This name must follow the OracleAS Portal rules for a valid component name, i.e.,:
     • It must be no more than 30 characters

     • It must contain only alphanumeric characters (no spaces or special characters allowed).

     • The first character must be a letter (not a number).

   • Enter the name that you want to display for this printer in the Display Name field. The Display Name is the name that is exposed to your users through OracleAS Portal.

     Note: The Display Name, unlike the internal Name, can have spaces in it.

   • Select the Portal DB Provider that will own the printer from the Portal DB Provider list of values. The Portal DB Providers displayed are those in which you have privileges to build components.

     Note: All components you add to or create in OracleAS Portal must belong to a Portal DB Provider. Refer to the OracleAS Portal online help, for more information on how to create a Portal DB Provider.

7. Click Next.

8. 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.

   • (Optional) Enter a description of the Printer in the Description field.

9. Click Next.

10. (Optional) Select an Availability calendar to restrict the days and times the printer can be used.

    See Also: Creating an Availability Calendar For more information on how to create an Availability Calendar.

11. Click Finish.

    The resulting page summarizes your settings for this printer. On this page, you can edit your settings, get detailed registration information about the printer, or delete it altogether.

    See Also: The Manage Portlet For more information on the fields and descriptions listed in the Manage portlet, i.e., Develop, Manage, and Access tabs.

12. Click Close to close this page and return to OracleAS Portal's Oracle Reports Security page.

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

11.2.3 Registering a Reports Server

Before you can define access controls for the Reports Server, you must register your server within OracleAS Portal. Registration provides OracleAS 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.

Table 11-2 Sample Values

Property	Sample Value
Name (internal name)	myrep_server
Display Name	My Reports Server
Portal DB Provider	PORTAL_APP
Reports Server Name	rep_machine_name, e.g., rep_myserver1
Oracle Reports Web Gateway URL for JSP reports	http://myias.mycomp.com:7778/
Oracle Reports Web Gateway URL for RDF reports	http://myias.mycomp.com:7778/reports/rwservlet
Availability Calendar	COMCAL

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

To register a Reports Server:

1. Log in as an administrator to OracleAS Portal.

2. Navigate to the Builder page.

3. Click the Administer tab.

4. Click the Oracle Reports Security Settings link in the Oracle Reports Security portlet. The Oracle Reports Security portlet enables you to use the security features in OracleAS Portal at the time of defining access to the server, printer, calendar, and reports definition file.

5. Click the Create Reports Server Access link in the Reports Server Access portlet.

6. On the resulting page, the Name (internal name) and the Portal DB Provider fields contain default values. To include custom values:
   • Enter a unique name in the Name field that will identify the Reports Server internally in OracleAS Portal, for example, MY_REPORTS_SERVER. This name must follow the OracleAS Portal rules for a valid component name, i.e.,:
     • It must be no more than 30 characters

     • It must contain only alphanumeric characters (no spaces or special characters allowed).

     • The first character must be a letter (not a number).

   • Enter the name you want to display for this server in the Display Name field. The Display Name is the name that is exposed to your users through OracleAS Portal.

     Note: The Display Name, unlike the internal Name, can have spaces in it.

   • Select the Portal DB Provider that will own the Reports Server from the Portal DB Provider list of values. The Portal DB Providers displayed are those in which you have privileges to build components.

     Note: All the components you add to or create in OracleAS Portal must belong to a Portal DB Provider. Refer to the OracleAS Portal online help, for more information on how to create a Portal DB Provider.

7. Click Next.

8. On the Server Definition page:
   • Enter the name of the Reports Server in the Reports Server Name field. This is the unique name assigned to the server at the time of installation, i.e.,rwserver -install repservername or rwserver server=repservername.

   • (Optional) Enter a description for the Reports Server in the Description field.

   • Enter the URL location of your JSP files in the Oracle Reports Web Gateway URL for JSP reports field. The URL should be in the following format:

     http://your_web_server.domain:port/
     
     

     For example:

     http://myias.mycomp.com:7779/
     
     

   • Enter the URL location of your Reports Servlet in the Oracle Reports Web Gateway URL for RDF reports field. The URL should be in the following format:

     http://your_web_server.domain:port/virtual_path_to_rwservlet/rwservlet
     

     See Also: Chapter 3, "Configuring OracleAS Reports Services" For more information on specifying the virtual path.

     For example:

     http://myias.mycomp.com:7778/reports/rwservlet
     
     

   • (Optional) Select the Run Only Registered Report Definition Files check box. This ensures that only the report definition files registered with OracleAS Portal can be executed on this Reports Server.

     Leave this box unchecked if you want this Reports Server to accept any report definition file, including those not registered in OracleAS Portal, as long as the user who submits the report request has access privileges to this Reports Server.

   • Select the printer(s) that you want to make available to this Reports Server from the Printers list. Use control-click (Windows) or click (UNIX) to select multiple printers.

9. Click Next.

10. (Optional) Enter a Custom Destination Type, if you have defined a custom destination type.

    See Also: Chapter 7, "Configuring Destinations for OracleAS Reports Services" For more information on custom destination types.

11. Click Next.

12. (Optional) Enter the Availability Calendar name or click the list button to select the Availability Calendar that determines the days and times this Reports Server is and is not available to accept report requests.

    See Also: Creating an Availability Calendar For more information on how to create an Availability Calendar.

13. Click Finish.

    The resulting page summarizes your settings for this Reports Server. On this page, you can edit your settings, get detailed registration information about the Reports Server, or delete it altogether.

    See Also: The Manage Portlet For more information on the fields and descriptions listed in the Manage portlet, i.e., Develop, Manage, and Access tabs.

14. Click Close to close this page and return to the Oracle Reports Security page.

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

11.2.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 OracleAS Portal parameter form, how users are to interact with the report.

User parameters are created in Reports Builder at the time of designing the report. You can assign values to these parameters when you run the report in OracleAS Portal.

Note: You can use the parameter settings available through OracleAS Portal to duplicate or create a subset of the parameters defined in Reports Builder at design time. At runtime, the Reports Server disregards any parameters that you set in OracleAS Portal not defined in Reports Builder at design time.

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

Note: Running reports from within OracleAS Portal requires the HTML iframe tag, which is not supported in Netscape 4.x. As a result, the following limitations apply when using Netscape 4.x: A report portlet cannot display in place if you are using HTTPS. You need to click on the portlet title to see the report in a separate browser window. A report portlet cannot be scheduled to run via the Customize link if you are using HTTPS.

Table 11-3 Sample Values

Property	Sample Values
Name (internal name)	Employee_Report
Display Name	Employee Report
Portal DB Provider	PORTAL_APP
Oracle Reports File Name	employee_report.jsp
Execute	as JSP
Name (Optional Parameters)	userid
Display Name (Optional Parameters)	User Identification

To register a report:

1. Log in as an administrator to OracleAS Portal.

2. Navigate to the Builder page.

3. Click the Administer tab.

4. Click Oracle Reports Security Settings link in the Oracle Reports Security portlet.

5. Click the Create Reports Definition File Access in the Reports Definition File Access portlet.

6. On the resulting page, the Name (internal name) and the Portal DB Provider fields contain default values. To include custom values:
   • Enter a unique name in the Name field that will identify the report internally in OracleAS Portal, for example, MY_REPORT. This name must follow the OracleAS Portal rules for a valid component name, i.e.,:
     • It must be no more than 30 characters

     • It must contain only alphanumeric characters (no spaces or special characters allowed).

     • The first character must be a letter (not a number).

   • Enter the name that you want to display for this report in the Display Name field. The Display Name is the name that is exposed to your users through OracleAS Portal.

     Note: The Display Name, unlike the internal Name, can have spaces in it.

   • Select the Portal DB Provider that will own the Reports Server from the Portal DB Provider list of values. The Portal DB Providers displayed are those in which you have privileges to build components.

     Note: All the components you add to or create in OracleAS Portal must belong to a Portal DB Provider. Refer to the OracleAS Portal online help, for more information on how to create a Portal DB Provider.

7. Click Next.

8. Enter or select information as follows:
   • Select the Reports Server(s) to be available to run this report from the Reports Servers list of values. Use control-click (Windows) or click (UNIX) to select multiple servers.

   • Enter the report file name, including its extension in the Oracle Reports File Name field.

     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. For JSPs, you need to define the name as virtual_path/reportname.jsp.

     See Also: Appendix B, "Reports-Related Environment Variables" For more information on Oracle Reports-related environment variables. Chapter 3, "Configuring OracleAS Reports Services" For more information on specifying the virtual path.

   • (Optional) Enter a description for this report in the Description field.

   • Select either via servlet or as JSP in the Execute field. The selection you make here will affect the choices that are available on the next wizard page.
     • via servlet: If you plan to run the report through the Reports Servlet.

     • as JSP: If you will run a deployed JSP report.

9. Click Next.

10. Select the Destination settings on the Required Parameters page.These settings are only applicable if you run your report 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:
    • Select the destination types from among Cache, File, Mail, OraclePortal, OracleWireless, Printer, FTP, WebDAV, or custom destination types. Types specifies the destination types acceptable for this report. If the server you associate with this report supports custom destination types, which you indicated when you registered the Reports Server in OracleAS 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. 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.

11. Select the Parameter Form Template and click Preview Template to see what the selected template looks like:
    • 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.

      Note: For information about adding your own templates to this list, see the OracleAS Portal online help.

12. Click Next.

13. Define the limits for the report's existing parameters on the Optional Parameters page:
    • Enter the name or user parameter to restrict the values available to users in the Name field. For example, SALES_REGION or COPIES.

    • Enter the display name of the system or user parameter. This name will be used to identify the parameter on the runtime parameter form.

    • Enter the name of the list of values, or select the values from a predefined list of values. The list must already exist. For information on creating a list of values, see the OracleAS Portal online help.

    • Enter the lowest value that you wish to set for a range of values in the Low Value field.

    • Enter the highest value that you wish to set for a range of values in the High Value field.

    • Click More Parameters if you wish to add more rows for additional parameters and values.

14. Click Next.

15. (Optional) Enter the Availability Calendar name or click the list button to select an existing Availability Calendar.

    Use the availability calendar to limit the days and times this report can be run.

    See Also: Creating an Availability Calendar For more information on how to create an Availability Calendar.

16. Click Next.

17. (Optional) 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.

18. 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.

    See Also: Publishing a Report in OracleAS Portal For more information on how to run your report from OracleAS Portal.

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

      Table 11-4 summarizes the options available on this page.

      Table 11-4 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	Select the Oracle Reports Server that you want to receive this report request. Only the servers that you chose at the time of registering the Report are displayed in this list box.
      Printer	Select the printer that you want to print your report output. Only the printers that you chose at the time of registering the report are displayed in this list box.
      Destype	Select the destination type. Only the destination types that you chose at the time of registering the report are displayed in this list box.
      Desformat	Select the destination format. Only the destination format that you chose at the time of registering the report are displayed in this list box.
      Desname	Enter the name of the output file when destype=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). For more information about SSOCONN, refer to SSOCONN.
      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.
      Portlet Width	Use this field to control the width of the portlet. You can enter the value as a percentage of the page (e.g., 90%) or in pixels (e.g, 700). If no value is specified, OracleAS Reports Services uses its default value (640 pixels wide).
      Portlet Height	Use this field to control the height of the portlet. You can enter the value as a percentage of the page (e.g., 50%) or in pixels (e.g, 400). If no value is specified, OracleAS Reports Services uses its default value (320 pixels high).
      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 15, "Creating Advanced Distributions".

11.2.5 The Manage Portlet

Use the Manage portlet page to perform actions on existing Oracle Portal portlets; for example, executing, editing, copying, dropping, or viewing information about the portlet.

The actions you can perform on the portlet depend on your privileges. Also, not all actions listed here are available for all portlets. The name of the portlet on which you can perform these actions appears in the upper left corner of the page.

Table 11-5 details the fields and descriptions listed in the Develop tab.

Table 11-5 The Develop Tab

Field	Description
(portlet Type and Name)	Displays the portlet's type and name; for example: Form (table) my_formfor a form based on a table called my_form.
Provider	Displays the name of the provider in which the portlet was created.
Version(s) Status (Not applicable to all portlets)	Displays all the versions of the portlet and the current status of each version. Click a status to edit the portlet version. Note: If there are no hyperlinks, you do not have privileges to edit the portlet.
Last Changed	Displays the name of the user who created or last edited the portlet, and the date and time when the portlet was created or last edited.
Run Link (Not applicable to all portlets)	Displays the URL for the procedure or procedures that, when executed, display the portlet. You can copy and paste this URL into another Web page to create a link to the portlet. Note: A procedure that executes the portlet without parameters has the suffix .show. A procedure that executes the portlet with parameters has the suffix .show_parms.
PL/SQL source (Not applicable to all portlets)	The portlet builder wizards create a PL/SQL package to represent each portlet: Package Spec: Displays the portlet's PL/SQL specification. Package Body: Displays the portlet's PL/SQL body.
Call Interface (Not applicable to all portlets)	Click Show to display the arguments that a portlet can accept that the end user can change at runtime. Also shown are examples of calling the portlet from a PL/SQL Stored Procedure and via a URL. When you run the package containing the portlet in PL/SQL or by calling it from a URL, you can edit the call interface to accept different arguments. Note: To view portlet source code, you must have Customize or Execute privileges on the portlet or the provider that owns it.
Edit Data Link (Not applicable to all portlets)	Click to connect to the URL containing the data, and to see and edit that data.
Edit	Click to edit the most recent version of the portlet. For example, you can reselect any table columns on which the portlet is based, change any fields or text that appear in the portlet, or choose a new look and feel.
Edit as New	Click to create and then edit a new version of this portlet. The existing portlet version does not change.
Edit Data (Not applicable to all portlets)	Click to see the spreadsheet and be able to edit the data within it.
Run	Click to run the current PRODUCTION version of the portlet. Note: If a valid package for the portlet doesn't exist, the portlet will not run.
Run As Portlet	Displays how the portlet will look as a portlet in a portal window (may look different than a full page display).
Customize	Click to display the customization form for the portlet. The customization form enables you to specify values that will be used to display the portlet. Note: If the current portlet is a form, Browse appears instead of Customize on this page.
Add to Favorites	Click to add the portlet to the Favorites list on your Oracle Portal Home page.
About	Displays stored attributes for the portlet.
Delete	Click to drop the portlet from the database.

Table 11-6 details the fields and descriptions listed in the Manage tab.

Table 11-6 The Manage Tab

Field	Description
Show/Hide SQL Query Info (Not applicable to all portlets)	Select to display or hide the SQL Query when running the portlet, for debugging purposes.
Show Locks on this portlet (Not applicable to all portlets)	Displays any locks currently active on the portlet (for example, if somebody else is editing it).
Export	Click to export the portlet from the database.
Copy	Click to copy the portlet from the database.
Rename	Click to rename the portlet (within the same provider).
Generate	Click to compile the PL/SQL package.
Monitor	Click to view a chart of all requests for the portlet and the users who made the request.

Table 11-7, Table 11-8, Table 11-9, Table 11-10, Table 11-11, Table 11-12, and Table 11-13 details the fields and descriptions listed in the Access tab.

Table 11-7 Portal Access

Field	Description
Publish as Portlet (Not applicable to all portlets)	Click to make the portlet available as a portlet. Note: To publish the portlet as a portlet, you must have the Publish Portlet privilege and you must make the provider that owns the portlet available via Expose as Provider on the Access provider page (Manage tab).

Table 11-8 Privilege Mode

Field

Description

Inherit Privileges from Provider

Select to allow the provider access privileges to override the portlet access privileges. Clear the check box and click Apply to allow the portlet access privileges to override the provider access privileges. In the Grant Access section, you can selectively grant or remove portlet access privileges for different users or groups (for example, Manage, Edit, View, Customize, or Execute). Note: To grant portlet access privileges to a user or group, you must have Manage access privileges on the portlet or provider that owns the portlet.

Table 11-9 Grant Access

Field	Description
Grantee	Enter the user or group to whom you want to grant the provider access privilege.
Execute	Choose the privilege you want to grant.
Add	Click to grant the provider access privilege.

Table 11-10 Change Access

Field	Description
Grantee	Displays the Oracle Portal user or group to whom the privilege is assigned. Click Error! Unknown switch argument.next to a grantee to delete all privileges.If you want to grant privileges to all Oracle Portal users, choose Public as the Grantee.
Type	Displays whether the grantee is an Oracle Portal user or group.
Privilege	Displays the privilege currently granted. To change a privilege, choose a new one and click Apply.

Table 11-11 Cell Privilege Mode

Field

Description

Inherit Privileges from portlet (Not applicable to all portlets)

Select to allow the portlet access privileges to override cell access privileges. Clear the checkbox and click Apply to allow cell access privileges to override the portlet access privileges. In the Alter Access section, you can selectively change cell access privileges for different users or groups (for example, Manage, Edit, View, Customize, or Execute). Note: To alter cell access privileges for a grantee, you must have Manage access privileges on the portlet or provider that owns the portlet.

Table 11-12 Alter Access

Field	Description
Grantee (Not applicable to all portlets)	Enter the user or group to whom you want to grant the cell access privilege.
Alter (Not applicable to all portlets)	Click to alter cell access privileges.

Table 11-13 Cache Invalidation

Field	Description
Clear Cache	Clears the cached version of the data, so that the next data request will be filled from the database.