4 Creating Report Jobs

This chapter describes how to use the BI Publisher scheduler to create and monitor report jobs. Report jobs can be scheduled to run at defined intervals and to be delivered to multiple destinations.

This chapter includes the following sections:

4.1 Navigating to the Schedule Report Job Page

Use the Schedule Report Job page to schedule a report job.

Navigate to the Schedule Report Job page in any of the following ways:

  • From the Home page: From the Create region, select Report Job.

  • From the catalog: Navigate to the report you want to schedule, then select the Schedule link.

  • From the Report Viewer: Click Actions and then click Schedule.

  • From the global header: Click New and then click Report Job.

The Schedule Report Job page contains four tabs to define the options for your report job: General, Output, Schedule, and Notification.

4.2 Setting General Options

The General tab is shown in Figure 4-1.

Figure 4-1 General Tab

general tab

Enter the following general information for the report job:

Table 4-1 General Information for the Report Job

Field Description

Report

If you accessed the schedule page from the report, this field displays the report path and name. If you accessed the schedule page from the Create region or the global header, click Choose to browse for and select the report to schedule.

Parameters

Any parameters defined for the report are displayed. Enter the values for this job.

Note: For date parameters, you can use an expression to increment the date for each run. For more information, see Section 4.9.1, "Incrementing Date Parameters."


4.3 Setting Output Options

The Output tab has two regions: Output and Destination. Each scheduled job can have multiple output files with distinct characteristics. Each output file can have multiple destinations. The Output tab is shown in Figure 4-2.

Figure 4-2 Output Tab

output tab

The options are described in Table 4-2:

Table 4-2 Output Tab Options

Option Description

Use Bursting Definition to Determine Output and Delivery Destination

Enable this option to use the report bursting definition for output and delivery. Once selected, all other fields on this page are disabled for selection. This option is only available when bursting is enabled for the report. For more information on report bursting, see Section 4.8, "Creating a Bursting Job."

Make Output Public

Enable this option to make this job output available to all users with permission to access this report. Users with access can view the report from the Report Job History page.

Save Data for Republishing

Enable this option to save the XML data that is generated for this job. Access the saved data from the Report Job History page (see Section 6.1, "Viewing Report Job History and Saved Output") where you can republish it, selecting a new layout and output options.


4.3.1 Adding Outputs

The Output Table enables you to create multiple report documents for one or more layouts using a combination of output format, locale, time zone, and calendar. To add outputs for this job, click the Add toolbar button to add an entry to the table. The fields are described in Table 4-3.

Table 4-3 Output Table Fields

Field Description

Name

Enter a name for this output.

Layout

Select the layout to apply to this output.

Format

Select the document output format. Output format is the type of document that is generated, for example, PDF, HTML, or Excel. The options available here are specified in the report definition.

Locale

Select the language-territory combination for this report output. This field defaults to the Report Locale defined in the user Preferences (see Section 2.2, "Setting My Account Preferences and Viewing My Groups").

Note: If the layout does not have an available translation for the selected locale, BI Publisher applies a locale fallback logic to select the layout. For more information, see "Locale Selection Logic" in Oracle Fusion Middleware Report Designer's Guide for Oracle Business Intelligence Publisher.

The appropriate number and date formatting are applied independently of the template translation.

Timezone

Select the time zone to use for this report output. The time zone defaults to the time zone defined in the user Preferences (see Section 2.2, "Setting My Account Preferences and Viewing My Groups").

Calendar

Select the calendar to use for this output.

Save Output

Select this box to save the report output. You must select this option to view your report from the Report Job History page.


4.3.2 Adding Destinations

Enter the delivery details in the Destination region. To deliver a report document to multiple destinations, select the Add Destination button and continue adding destinations as needed.

Note:

Delivery servers are set up in the Administration page. For more information, see "Setting Up Delivery Destinations" in Oracle Fusion Middleware Administrator's Guide for Oracle Business Intelligence Publisher.

If you do not require a destination, leave this region blank. Select Save Output to view the output from the Report Job History page. For more information, see Section 6.1, "Viewing Report Job History and Saved Output."

For each destination you add, select from the Output list which documents to send to this destination, as shown in Figure 4-3.

Figure 4-3 Output list

Output list

Enter the appropriate fields for each destination type:

4.3.2.1 Email

Enter multiple e-mail addresses separated by a comma. Enter any Message text to include with the report.

4.3.2.2 Printer

Select the Printer Group and the Printer, enter the Number of copies, and select Single sided or Double sided (the printer must support duplex printing for this option to take effect). Optionally select the printer Default Tray from which to print the report, and the Print Range pages.

4.3.2.3 Fax

Select the Fax server to deliver the report and enter the Fax number to which to send the report.

4.3.2.4 FTP

Select the FTP Server to deliver the report and enter valid Username and Password credentials.

Remote Directory - enter the directory to which to deliver the document (example: /pub/). To deliver the document to the user's home directory, enter '.'

Remote File Name - enter the file name for BI Publisher to assign to the delivery document on the remote server (example: myreport.pdf).

To assign a file name dynamically using a date expression, see Section 4.9.2, "Defining a Destination File Name Dynamically Using a Date Expression."

Use Secure FTP - select the box to use secure FTP.

4.3.2.5 Web Folder

Select the Web Folder Server where you want the report delivered and enter valid Username and Password credentials.

Remote Directory - enter the directory to which to deliver the document (example: /pub/). If no value is entered, then the document is delivered to the login directory.

Remote File Name - enter the file name for BI Publisher to assign to the delivery document on the remote server (example: myreport.pdf).

To assign a file name dynamically using a date expression, see Section 4.9.2, "Defining a Destination File Name Dynamically Using a Date Expression."

4.4 Defining the Schedule for a Job

Use the Schedule tab to define when to execute the report job. The scheduler supports defining a simple recurrence pattern as well as conditionalizing the report job submission based on a condition defined in a report trigger. The Schedule tab is shown Figure 4-4.

Figure 4-4 Schedule Tab

Schedule tab

4.4.1 Defining a Recurrence Pattern

Select from the following recurrence pattern options:

4.4.1.1 Once

Select Run Now or use the date selector to enter the specific Start date and time.

4.4.1.2 Hourly/Minute

Every - select Hour(s) or Minute(s) and enter the appropriate integer value for the increment.

Start - use the date selector to enter the date and time to start running this job.

End - (optional) use the date selector to enter an end date and time for this job.

4.4.1.3 Daily

Every - enter the increment in days. For example, to run the report every day enter 1; to run the report every other day, enter 2.

Start - use the date selector to enter the date and time to start running this job. The time selected determines the time that the job is executed each day that it runs.

End - (optional) use the date selector to enter an end date and time for this job.

4.4.1.4 Weekly

Every - enter the increment in weeks and select the desired day or days of the week. For example, to run the report every Tuesday and Thursday, enter 1, and then select Tuesday and Thursday. To run the report every other Wednesday, enter 2, and select Wednesday.

Start - use the date selector to enter the date and time to start running this job. The time selected determines the time that the job is executed for each run.

End - (optional) use the date selector to enter an end date for this job.

4.4.1.5 Monthly

Every - select each month that the job executes.

On - select either a day of the week, for example: 1st Monday of every month; or select a specific day of the month, for example: 15.

Start - use the date selector to enter the date and time to start running this job. The time selected determines the time that the job is executed for each run.

End - (optional) use the date selector to enter an end date for this job.

4.4.1.6 Annually

Every - enter the increment in years that the job executes.

On - select either a day and a month, for example: Day 1 of January; or select a day of the week of the month, for example: First Monday of January.

Start - use the date selector to enter the date and time to start running this job. The time selected determines the time that the job is executed for each run.

End - (optional) use the date selector to enter an end date for this job.

4.4.1.7 Specific Dates

Add Date - use the date selector to enter the specific date and time to run the job. Add multiple specific dates as needed.

4.4.2 Enabling a Schedule Trigger

A schedule trigger tests for a condition and if the condition returns a result, the job executes. If the trigger condition is not met, the job instance is skipped. You can also set up a repeat schedule for the trigger to keep checking for the condition. If the condition is not met, you can set the time interval (in minutes) to wait before the trigger is executed again.

Some examples of when you would use a schedule trigger are:

  • A report job should only run after the successful completion of an extract, transfer, and load process

  • Account management wants a report triggered if any of the receipts from the previous day exceed a specified amount

  • Human resources needs a report only when new hires entered the system in the previous week

Triggers are set up in the data model and then they are available for selection from the Schedules tab. You can associate a schedule trigger that is defined in any data model; the trigger does not have to be defined in the data model of the report that is being run. One trigger per report job is supported.

For more information about setting up schedule triggers in a data model, see "Adding Event Triggers" in Oracle Fusion Middleware Data Modeling Guide for Oracle Business Intelligence Publisher.

To enable a schedule trigger:

  1. Select Use Trigger.

  2. (Optional) Set the Retry Limit value to specify the maximum number of times to execute the schedule trigger to check for the condition. The default value is 1 and only positive integer values are allowed in this field.

  3. (Optional) Set the Pause Time value to specify the number of minutes to wait before re-executing the schedule trigger. If the Retry Limit value is set to a value greater than 1, this field is enabled. Only positive integer values are allowed in this field.

    Note:

    The retry limit and pause time should not exceed the recurrence schedule time interval.

    If the condition returns false when the maximum number of attempts is reached, then the job status is displayed as Skipped.

  4. Select the Data Model that defines the schedule trigger. When the data model is selected, the Trigger list displays the schedule triggers defined in the data model.

  5. Select the trigger from the list.

  6. If the schedule trigger includes parameters, select values as appropriate.

Figure 4-5 shows a schedule trigger with one parameter enabled for a report job.

Figure 4-5 Schedule Trigger Enabled for a Report Job

Schedule trigger enabled for a report job

4.5 Configuring Notifications

A notification is a message that a job has finished processing. BI Publisher supports the following notification statuses:

  • Report completed

  • Report completed with warnings

  • Report failed

  • Report skipped

BI Publisher supports two methods of notification: e-mail and HTTP.

Note:

Configure the delivery e-mail servers and HTTP servers in the Administration Delivery Configuration page, see "Setting Up Delivery Destinations" in Oracle Fusion Middleware Administrator's Guide for Oracle Business Intelligence Publisher.

4.5.1 Adding Notifications

Use the Notification tab to configure notifications for a job, as shown in Figure 4-6.

Figure 4-6 Notification Tab

Notification tab

4.5.1.1 Email

To enable an e-mail notification:

Select the report completion statuses for which to send the notification, and enter a comma-separated list of addresses.

4.5.1.2 HTTP

To enable an HTTP notification:

Select the report completion statuses for which to send the notification. Select the server to which to send the HTTP notification. Enter the user name and password for the server, if required.

4.6 Submitting and Monitoring a Job

Select Submit. This invokes the Submit Job dialog with confirmation details for you to review. Enter a name for this job and click Submit.

To suspend, edit, or delete a job, navigate to the Manage Report Jobs page as follows: On the global header, click Open and then click Report Jobs. For more information, see Section 5.1, "About the Manage Report Jobs Page."

To monitor a running job or to see the results, navigate to Report Job History page as follows: On the global header, click Open and then click Report Job History. For more information, see Section 6.1, "Viewing Report Job History and Saved Output."

4.7 Creating a Job from an Existing Job

Create a new job from an existing job in the Manage Report Jobs page:

  1. Navigate to the Manage Report Jobs page: On the global header, click Open and then click Report Jobs.

  2. Use the filter criteria to find the existing job. In the results table, click the Edit icon to open the job for editing.

  3. Enter the details for the new job definition. When finished, click Submit as New as shown in the following figure:

    Editing a job to submit as new
  4. Enter a name for the new job and click Submit As.

For more information about editing jobs in the Manage Report Jobs page, see Section 5.9, "Editing Jobs."

4.8 Creating a Bursting Job

Bursting is the splitting of the report data into multiple blocks based on a key field in the data and then applying specific parameters for the layout and delivery for each block of data. For example, a customer invoice report can be burst to deliver each customer's invoice to their own e-mail address. A bursting definition for a report is set up in the report's data model. For more information, see "Adding a Bursting Definition to Your Data Model" in Oracle Fusion Middleware Data Modeling Guide for Oracle Business Intelligence Publisher.

If the report has been enabled for bursting, the Use Bursting Definition to Determine Output & Delivery Destination box on the Output tab is enabled. If you select this option, the Output and Destination options for the job are disabled because output and destination details are supplied by the bursting definition.

Enable a report to use a bursting definition on the Report Properties dialog of the report editor. For more information, see "Configuring Report Properties" in Oracle Fusion Middleware Report Designer's Guide for Oracle Business Intelligence Publisher.

4.9 Advanced Topics

This section includes the following topics:

4.9.1 Incrementing Date Parameters

If the scheduled report includes date parameters, when you enter the values for the dates for the schedule, these values are not updatable. Therefore, every time a scheduled instance of the report is run, the same date parameters are used. If you require that the date parameters be incremented for each run, then you can enter an expression in the date parameter field of the scheduler to calculate the date each time the report job executes.

For example, assume you create a schedule for a report that runs every Monday to capture data from the previous week. Each week you need the date parameters for the report to increment to the first and last days of the previous week.

Enter one of the following functions using the syntax shown to calculate the appropriate date at the scheduled runtime for the report:

  • {$SYSDATE()$} - current date (the system date of the server on which BI Publisher is running)

  • {$FIRST_DAY_OF_MONTH()$} - first day of the current month

  • {$LAST_DAY_OF_MONTH()$} - last day of the current month

  • {$FIRST_DAY_OF_YEAR)$} - first day of the current year

  • {$LAST_DAY_OF_YEAR)$} - last day of the current year

The date function calls in the parameter values are not evaluated until the report job is executed by the Scheduler.

You can also enter expressions using the plus sign "+" and minus sign "-" to add or subtract days as follows:

  • {$SYSDATE()+1$}

  • {$SYSDATE()-7$}

For this example, to capture data from the previous week, each time the schedule runs, enter the following in the report's date parameter fields:

  • Date From: {$SYSDATE()-7$}

  • Date To: {$SYSDATE()-1$}

Note:

The date functions can also be set up as default parameter values in the data model. In this case, every time a user views the report from the report viewer, the date parameter is calculated according to the expression supplied for the default value. For more information, see "Adding Parameters and Lists of Values" in Oracle Fusion Middleware Data Modeling Guide for Oracle Business Intelligence Publisher.

4.9.2 Defining a Destination File Name Dynamically Using a Date Expression

When entering the remote file name for a Web folder or FTP destination, you can enter a date expression to have BI Publisher dynamically include a date expression in the file name. The date is set at runtime, using the server time zone.

The supported date expressions are described in Table 4-4.

Table 4-4 Supported Date Expressions

Expression Description

%y

Displays the year in four digits: Example: 2011

%m

Displays the month in two digits: 01-12 (where 01 = January)

%d

Displays the date in two digits: 01-31

%H

Displays the hour in two digits based on 24-hour day: 00-24

%M

Displays the minute in two digits: 00 - 59

%S

Displays the number of seconds in two digits: 00 - 59

%l

Displays milliseconds in three digits: 000 - 999


4.9.2.1 Examples

Creating a File Name That Appends a Date

To create a file name that appends the day, month, and year, such as:

myfile_01_11_2010.pdf

Enter the following:

myfile_%d_%m_%y.pdf

Creating a File Name That Prefixes a Date and Appends a Time

To create a file name that prefixes the day, month, and year and appends the hour and minute, such as:

01_01_2010_myfile_22_57.pdf

Enter the following:

%d_%m_%y_myfile_%H_%M.pdf

Note:

If the file name includes an undefined expression, such as my_file_%a%b%c.pdf, the file is created as named: "my_file_%a%b%c.pdf".