Overview - Schedule Reports to Run in the Future

Main Page | Discussion | Edit | History | Help | Switch to MediaWiki mode

---

---

In this lesson you'll schedule a report to run every night and to save the resulting report document to the server. This lesson demonstrates:

• Provide parameters to reports.
• Schedule reports to run on a regular basis.
• Monitor the status of your completed, active, and pending jobs.

Contents 1 Introduction 2 Schedule a Report to Run In Ten Minutes 3 Set Parameters 4 Report Document Destination 5 Job Status 6 Monitor Your Job Queue 7 Schedule a Report to Run Every Morning 8 Finishing Up 9 Learn More

Introduction

We've already seen how to run a report on demand. iServer Express also lets you schedule reports to run in the future: either once or on a schedule. Each run of a report is called a "job", also sometimes called asynchronous jobs, batch jobs, batch reports, or background jobs. Each job runs a report and stores the resulting report document in a specified folder in the iServer Express folder system. iServer Express needs three pieces of information when you schedule a report to run later:

• When you want the report to run,
• Parameters (if any) that select the data to appear in the report, and
• Where you want to store the completed report.

Let's see this in action.

• Use the iPortal to navigate to the folder “Public > BIRT and Business Reports Examples”.
• Find the “Product Sales by State” report, and click on the “schedule” icon next to it (the clock):

A new browser window pops up, with three tabs: Schedule, Parameters, and Save As. This report has a required parameter, so the Parameters tab appears. (If the report had no parameters, this tab would not be displayed).

Schedule a Report to Run In Ten Minutes

• We want to schedule the report to run 10 minutes from now. So, for “Scheduling Options” select the “Once” radio button.

The screen changes and now displays fields where you can set the date and time when the report should run.

By default, the date and time are set to ten minutes from now, so you don’t have to change them.

Set Parameters

• Click the “Next” button to move on to the next tab, Parameters:

• Click on the drop-down list box on the Parameters page to see all the possible choices for the “product code” parameter.

iPortal makes it easy for report developers to specify that certain report parameters should be drop-down list boxes, checkboxes, radio buttons etc. Report developers can also tell iPortal to populate the list of all possible values for a parameter from a database. This particular report has a drop-down list for the "product code" parameter.

This report dynamically obtains the values in the drop-down list from the database. Another report could choose to use radio buttons or free-form text fields for the parameter. Or the report could hard-coded the possible parameter values instead of having them dynamically retrieved from a data source.

• Select the value "S12_1108-2001 Ferrari Enzo" from the drop-down list.

Report Document Destination

• Select the Next button to go to the next tab: “Save As”.

The “Save As” tab appears:

For this example we want to directly generate a PDF file and have it stored to iServer in the user’s home folder.

You will most often save report documents directly as report document instead of as PDF. A report document enables the full viewer features we saw earlier, including the ability to exported to PDF, Word, Excel, or PowerPoint format. In contrast, if your job directly generates PDF instead of a report document, you will not be able to later use the viewer or export the report. We use PDF here just to show how it is done is all you need.

iServer Express provides file versioning, something like a source code management system. Reports often run repeatedly, such as once per day. You will usually want to retain several day's output, say, the last five days. Rather than give each document a unique name "Sales Detail for March 13", say, iServer Express instead stores these documents as versions. Version 1 might be for March 11, version 2 for March 12, version 3 for March 13, etc. Versions can be a bit confusing at first if you've never used them in other systems, but you'll quickly appreciate them as you start accumulating report documents.

Let's see this in action:

• Leave the default values for Headline, Output location, Document name, and Version name.
• For “Document Format”, select PDF from the drop-down list.
• New form fields specific to PDF output appear. Accept their default settings.
• Leave the box for “send me an email notification” unchecked.

iServer Express supports e-mail notification, but this feature is not available when you first install the software. Before you can use e-mail notification, you must configure the feature using the Configuration Console. Once e-mail is available, you can click the “Send me an email notification” checkbox. You can optionally attach the report to the e-mail in any of the export formats (Word, Excel, etc.) If you want an email without the report attached, you can select “no attachment” from the drop-down list; the email notification will include a hyperlink to the report’s location on iServer Express.

• Accept the default settings for “If the file already exists” and “Keep only the latest X versions”.
• Click Finish to submit the job.

Job Status

The job status dialog appears:

• Click the “Job Status” button to view more detail on this report schedule.

• Close this browser window and return to the window containing the Documents listing.

Monitor Your Job Queue

• Click on “My Jobs” in the left sidebar.

“My Jobs” lets you monitor the progress of scheduled jobs through the queue. You’re on the “Completed” jobs tab at first. There is nothing listed because your scheduled job has not run yet (it will run within the next 10 minutes).

• Click on the Schedules tab and you should see your job listed. The “next run” is sometime within the next 10 minutes.

At the time the job is to run you will see the job move to the Pending tab as it prepares to run, then to the Running tab once it starts to actually run, and finally to the Completed tab. After the report is completed, the Completed tab will look like this:

You can see that the most recent report run succeeded. There is also a link to directly open up the resultant PDF. You can also see that the schedule is expired, meaning that this job will not recur in the future.

• Click on My Folder link in the upper right corner to go to the administrator user’s home folder. You will see the newly created PDF document listed.

Schedule a Report to Run Every Morning

You just scheduled a job to run one time. However, most scheduled jobs run on a repeated schedule. Let’s set up a job that will run the Order Details report every morning at 5:00 am. Each time the report runs the server will create a new report document version. We’ll keep the latest 5 days of Order Details report documents on iServer and after 5 days the older documents will automatically be deleted from the server.

• Return to the /Public/BIRT and Business Reports Examples folder
• Click on the clock icon next to the Order Details report.

• Next to “Scheduling Options”, select “Recurring”.
• New fields will appear on the screen. Fill in “Every Day” from the drop-down list box, and enter “5:00 am” for the time.
• Check the “Starting” and “Until” checkboxes. Click on the calendar icon next to each, and a calendar control will pop up. For the “Until” line, use the calendar date picker to select an end-date sometime in the future.
• Click the Next> button.
• The “Save As” tab appears:

On the “Save As” tab we'll leave everything as set by default except at the bottom under “If the file already exists.” Because we’re going to run this report every day, we’ll be generating a lot of report documents that have the same name. These will be saved as versions of our report document. To specify that we’re going to keep the latest 5 days of documents on iServer at any time:

• Select the “Create a new version” radio button.
• Check the “Keep only the latest X version(s)” checkbox, and enter “5” in the box.

Finishing Up

• Click the Finish Button.
• A job status screen will be displayed. When you’re ready, dismiss this window.
• Look at your job schedule in the “My Jobs → Schedule” queue.

Learn More

The following product manuals at http://www.birt-exchange.com/modules/documentation/ provide more information.

• If you are a BIRT user: BIRT Deployment → iServer Express Report Server → Using Actuate iServer Express →, or
• If you are an e.Spreadsheet user: Spreadsheet Automation → iServer Express Report Server → Using Actuate iServer Express →
  • Managing Reports →
  • Scheduling, running, and managing reports
  • Running reports with parameters
  • Generating reports →
    • Running a job
    • Specifying job parameters
    • Checking the status of a job

The same documentation is available in your iServer Express install:

• http://localhost:8900/iportal/help/wwhelp/wwhimpl/js/html/wwhelp.htm → Using iPortal for Actuate iServer Express → Managing Reports (substitute the proper machine name for "localhost" if iPortal is on another machine.)

You can simply click on the Help link on each of the iPortal pages to get help with that specific page.

---

---

This page has been accessed 1,102 times. This page was last modified 05:50, 15 July 2008.