Skip Headers

Oracle® Application Server Reports Services Publishing Reports to the Web 10g Release 2 (10.1.2) B14048-02 |
| Library | Product | Contents | Index

Previous | Next |

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

- Registering Oracle Reports Components

- Publishing Your Report as a Portlet

- Troubleshooting Information

Before you deploy reports, both OracleAS Portal and OracleAS 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 OracleAS Reports Services The Oracle Application Server Portal Configuration Guide for information on configuring OracleAS Portal The Oracle Application Server Installation Guide for information on installing both components The Oracle Application Server documentation CD The Oracle Technology Network, (`http://www.oracle.com/technology/index.html`)

## 12.1 Creating Reports Users and Named Groups

If you use the security features in OracleAS Portal to control access to your reports, you must register all of your Reports users in Oracle Internet Directory 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 features to synchronize the directories and save yourself the effort of entering your users individually. You'll find information about Oracle Internet Directory's Directory Integration Server in the Oracle Internet Directory 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 OracleAS 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 using the environment switching functionality to dynamically set the environment for reports. Refer to Section 3.2.2, "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

### 12.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 (for example, 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 (for example, 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.

Note: Users can run Web commands (such as `getjobid`, `getserverinfo`, `showjobs`, and `showenv`) if they are in one of the listed RW_ groups. The RW_ groups are created automatically by configuring OracleAS Portal, or you can create them manually. With Oracle Reports 10g Release 2 (10.1.2), users can also run Web commands if they are in the IASADMINS group.

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

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

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

#### 12.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 OracleAS Reports Services.

### 12.1.2 Creating Users and Groups

OracleAS Portal uses the Delegated Administration Service (DAS) interface to Oracle Internet Directory 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 (for example, 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 (for example, 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 (for example, JSMITH) rather than groups, but this approach is more difficult and time consuming to manage.

## 12.2 Registering Oracle Reports Components

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 on joining privilege groups in OracleAS Portal, refer to the Oracle Application Server Portal Configuration Guide.

This section outlines the necessary steps to go about:

- Registering a Reports Server

- Registering a Report

- Registering a Printer

- Creating an Availability Calendar

To perform actions on existing OracleAS Portal portlets, refer to:

- The Manage Portlet

### 12.2.1 Registering a Reports Server

Before you can define access controls for a 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 12-1 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``, for example, 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`

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; that is:

     - 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; that is,`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 8, "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: Section 12.2.4, "Creating 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: Section 12.2.5, "The Manage Portlet" for more information on the fields and descriptions listed in the Manage portlet (that is, 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.

### 12.2.2 Registering a Report

Registering a report is a required step that enables 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, through 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 the portlet title to see the report in a separate browser window. A report portlet cannot be scheduled to run through the Customize link if you are using HTTPS.

Table 12-2 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; that is:

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

     See Also: Appendix B, "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.

   - In the Execute field, select either through servlet or as JS. The selection you make here will affect the choices that are available on the next wizard page.

     - through 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:

    - Types specifies the destination types acceptable for this report. Select the destination types from among Cache, File, Mail, OraclePortal, OracleWireless, Printer, FTP, WebDAV, 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 OracleAS Portal, the types you indicated will display on this list.

    - Formats defines the acceptable output format(s) for this report. Choose from HTML, HTMLCSS, PDF, XML, RTF, Delimited, Spreadsheet, 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: Section 12.2.4, "Creating 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: Section 12.3, "Publishing Your Report as a Portlet" for more information on how to run your report from OracleAS Portal.

19. Click the Access tab and select the Publish as Portlet box. This adds the report to the Portlet Repository, allowing you to add it to a page and publish your report as a portlet.

20. Click Customize to view the report's Runtime Parameter Form.

    Table 12-3 summarizes the options available on this page.

Table 12-3 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`=`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 on `SSOCONN`, refer to Section 11.3.3.1, "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 (for example, 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 (for example, 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 on the distribution XML file, see Chapter 15, "Creating Advanced Distributions".

### 12.2.3 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 standalone 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 12-4 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; that is:

     - 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 through 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: Section 12.2.4, "Creating 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: Section 12.2.5, "The Manage Portlet" for more information on the fields and descriptions listed in the Manage portlet (that is, 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.

### 12.2.4 Creating an Availability Calendar

Defining availability calendars is an optional step that enables 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.

#### 12.2.4.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; that is:

     - 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 indicates that 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 indicates that 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 indicates that 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 (for example, always on the 25th through the 29th of the month) or by the particular day(s) (for example, always on Monday through Friday—which happen this month to fall on the 25th through the 29th).

    - Weekly indicates that the duration period restarts on a weekly basis between the days specified under Duration.

    - Daily indicates that 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 OracleAS Reports Services components.

#### 12.2.4.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; that is:

     - 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: Section 12.2.5, "The Manage Portlet" for more information on the fields and descriptions listed in the Manage portlet (that is, 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 OracleAS Reports Services components.

### 12.2.5 The Manage Portlet

Use the Manage portlet page to perform actions on existing OracleAS 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 12-5 details the fields and descriptions listed in the Develop tab.

Table 12-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 through 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 OracleAS Portal Home page.
About | Displays stored attributes for the portlet.
Delete | Click to drop the portlet from the database.

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

Table 12-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 12-7, Table 12-8, Table 12-9, Table 12-10, Table 12-11, Table 12-12, and Table 12-13 details the fields and descriptions listed in the Access tab.

Table 12-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 through Expose as Provider on the Access provider page (Manage tab).

Table 12-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 12-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 12-10 Change Access

Field | Description
--- | ---
Grantee | Displays the OracleAS 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 OracleAS Portal users, choose Public as the Grantee.
Type | Displays whether the grantee is an OracleAS Portal user or group.
Privilege | Displays the privilege currently granted. To change a privilege, choose a new one and click Apply.

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

## 12.3 Publishing Your Report as a Portlet

After you have registered your Oracle Reports, you can expose your report in a portal by performing the following steps:

1. Create a provider for your reports. This step defines a provider to contain the reports you wish to make available to users in the portal. Alternatively, you can use the existing providers included, by default, with OracleAS Portal.

   Refer to Section 12.3.1, "Creating a Provider for Your Reports".

2. Add the report as an item linkFoot 1 or as a portletFoot 2 to a page and optionally customize it. This makes the report available to users on a page and enables the page designer to set the report parameters and schedule it to run automatically.

   Refer to:

   - Section 12.3.2, "Adding the Report Portlet to a Page"

   - Section 12.3.3, "Adding the Reports Component as an Item Link to a Page"

   - Section 12.3.4, "Running Reports on OracleAS Portal as an Item Link on a Nondefault Installation"

### 12.3.1 Creating a Provider for Your Reports

If you do not already have a provider defined to contain your reports, you need to create one. For more information on creating a provider, see the OracleAS Portal online Help.

Note: The provider that contains your reports must be a database provider and must have the Expose as Provider setting selected on its Access page.

### 12.3.2 Adding the Report Portlet to a Page

After you have registered your report with OracleAS Portal, you can publish it as a portlet on your portal page.

Note: You must have enabled the Publish as Portlet box to ensure that you can publish your report as a portlet.

To publish a report as a portlet:

1. If you are not already on the Builder page, click Builder at the top of the page.

2. Click the Build tab.

3. In the Page Groups portlet, choose the name of the page group in which you want to place your report portlet.

4. Create a new page by clicking Create a Page or edit an existing page by entering the name of an existing page and clicking Edit.

5. If you are creating a new page, follow the steps in the wizard and click the question mark in the upper right corner for additional information about the available settings. Click Finish when you are done.

   See Also: Section 12.3.3, "Adding the Reports Component as an Item Link to a Page" for information on how to add the Oracle Reports item to a page.

   If you are editing an existing page, skip to the next step.

6. In the page region where you wish to add your report portlet, click the Add Portlet tool.

   Tip: Hints for each tool will display when you roll your mouse over them.

7. Drill down through the Portlet Repository to the provider that contains the report portlet. The report portlet is listed in the Portlet Repository under the Portal DB Provider to which it belongs. The location of the provider depends on how the Portlet Repository has been organized. If the Portal DB Provider is a fairly new provider, it may be under the New page of the Portlet Repository.

8. Click the name of your report portlet to add it to the Selected Portlets list.

9. Click OK.

10. Click Customize in the upper right corner of your report portlet.

11. Enter parameter values in the Parameter tab and, if desired, schedule the job to run automatically in the Schedule tab.

12. You can control the size of the portlet by specifying the Portlet Width and Portlet Height parameters on the Customize page for the Reports Definition File object. The value of these parameters may be a percentage (%) or a number of pixels.

    For example, you can enter:

    Portlet Width: 90%

    Portlet Height: 480

    If no value is specified, OracleAS Reports Services uses its default value (640 pixels wide and 320 pixels high).

    If the Portlet Width and Portlet Height fields are visible to users, then they can also adjust each portlet's width and height through Customize. The user's value will override the value set in the Customize page of the Reports Definition File Object component.

13. You can choose whether to make a report's parameters visible to users on the Customization page of a Reports Definition File Access component.

    To make a report's parameters visible to users:

    1. Click Customize at the bottom of the Develop tab for the report.

    2. Select Visible to user for each parameter you want to expose.

       Note: You can also set the default value of the parameter from this page.

       If the parameter you are exposing has a corresponding OracleAS Portal page parameter, and you leave the parameter value empty in the Customize page, the portlet inherits the page parameter's value. If the user enters a value for the report portlet's parameter, that value will override the page parameter value.

    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 or if it is not a JSP report. You need to click the portlet title to see the report in a separate browser window. A report portlet cannot be scheduled to run through the Customize link if you are using HTTPS.

### 12.3.3 Adding the Reports Component as an Item Link to a Page

You can add an Oracle Reports component to a page as an item link using the Oracle Reports item type. If you have installed OracleAS Portal with the nondefault language setting, refer to Section 12.3.4, "Running Reports on OracleAS Portal as an Item Link on a Nondefault Installation".

Note: This item type must be included from the hidden list of item types and can be configured only if you are the page group administrator.

1. If you are not already on the Builder page, click Builder at the top of the page.

2. Click the Build tab.

3. In the Page Groups portlet, choose the name of the page group in which you want to place your report item link.

4. Create a new page by clicking Create a Page or edit an existing page by entering the name of an existing page and clicking Edit.

5. If you are creating a new page, follow the steps in the wizard and click the question mark in the upper right corner for additional information about the available settings. Click Finish when you are done.

   If you are editing an existing page, skip to the next step.

6. Click the Add Item link. The Oracle Reports item type is available as a hidden item type. To include it as an available item type, click the configure the list of available item types link.

7. Select Oracle Reports in the Hidden Item Types list and click the right arrow (>) to move it to the Visible Item Types list. Alternatively, you can click >> to move all items in the Hidden Item Types list to the Visible Item Types list.

8. Click OK.

9. Select the Oracle Reports item type in the Content Item Types menu and click Next to display the Add Oracle Reports page.

10. Enter a Display Name that users of your portal will view when clicking your report.

11. Select from the list of available default Oracle Reports components.

12. Select Display Parameter Form if your report requires any user inputs before your report is displayed.

13. Select Link That Displays Item In New Browser Window to ensure that the report is viewed in a separate page.

14. Click Finish. The Oracle Reports item now displays as a link in your page.

15. Click the link to run the report and provide any parameters required, if Display Parameter Form is selected.

### 12.3.4 Running Reports on OracleAS Portal as an Item Link on a Nondefault Installation

When you install OracleAS Portal with a nondefault language setting, some entries required to publish a report as an item link on a portal page are not installed automatically. You must install the language of your choice by using the rwlang.sql script.

Thus, you must run the script `rwlang.sql` (`ORACLE_HOME/portal/admin/plsql/wwd/`) if both of the following are true:

- You have selected at least one language in addition to the default ("`US`") at the time of installing OracleAS Portal.

- You want to publish a report as an item link in OracleAS Portal.

Note: This is a one time post-installation task and will ensure that you can publish a report as an item link on OracleAS Portal.

To run the script:

1. Change the directory to `ORACLE_HOME/portal/admin/plsql/wwd/`.

2. Run `sqlplus`.

3. Log on to OracleAS Portal using the portal schema.

4. This is the portal schema used to install OracleAS Portal PL/SQL packages.

5. Run the rwlang.sql script with the following parameters:

       @rwlang.sql language_list

   where

   `language_list` is the list of languages separated by commas.

   For example, to install French and Japanese:

       @rwlang.sql f,ja

Usage Note

- There should be no space before or after the comma (,) because sqlplus treats the language list as two parameters, instead of one parameter separated by a comma (,).

- The header of the rwlang.sql script contains the complete list of all language abbreviations. Edit the script file using any text editor to find out the various abbreviations.

## 12.4 Troubleshooting Information

This section contains information on the various steps that you can take to rectify issues that occur.

### 12.4.1 Resolving Reports-Portal Integration Error When Attempting Create Resource

In OracleAS Portal, when configuring Oracle Reports Security settings for Reports Definition File Access, you may encounter an error when editing a report definition file, when you click Run or Run as Portlet.

    500 Internal Server Error
    Unexpected Error. Please contact Administrator

This error occurs when all of the following conditions are true:

- Running in an Interop deployment (which allows for a mixed 9.0.2/9.0.4 environment), with 9.0.4 MT (mid-tier), 9.0.4 IM (Identity Management), and 9.0.2 MR (metadata repository) configured to run together.

- Running Oracle Reports within OracleAS Portal, using the SSOCONN parameter.

- The connection resource specified in the SSOCONN parameter has not been created in the Oracle Internet Directory server.

To implement the workaround, perform the following steps:

1. In the 9.0.4 IM `ORACLE_HOME`, open the following file in a text editor:

       ORACLE_HOME/Apache/Apache/conf/mod_osso.conf

2. Add the following flag:

       OssoRedirectByForm on

   For example:

       <IfModule mod_osso.c>
       OssoIpCheck off
       OssoIdleTimeout off
       OssoConfigFile
       /private1/iasinst/install_set1/904infra/Apache/Apache/conf/osso/osso.conf
       OssoRedirectByForm on
       </IfModule>

Footnote Legend

Footnote 1: An individual piece of content (text, hyperlink, image, and so on) that resides on a page in an item region.
Footnote 2: A reusable, pluggable Web component that typically displays portions of Web content.