Scheduling Objects

One of the many benefits of using Crystal Enterprise for managing your organization s reporting and analysis infrastructure is its ability to schedule reports. This allows automatic running of reports on a daily, weekly, or monthly basis, or on other regular schedules that suit your particular environment. CE 10 also introduces program objects (executable programs, Java programs, or script) that can also be scheduled on a regular basis. And, new CE 10 Object Packages, consisting of groups of related reports or program objects, can be scheduled as well.

Note  

The majority of scheduling discussions in this section pertain to reports. Program object scheduling options are generally limited to specifying the frequency of the schedule, any command- line arguments supplied when run, and the destination of the program s output text. The remaining scheduling options apply to reports only.

When you schedule a report or program object, you are setting a time to run it ”either once or on a recurring schedule. You can schedule a report to run immediately, if desired; the difference between doing this and viewing on demand is that Crystal Enterprise saves the instance of the report when it is run, and makes it available to other users. Unlike the temporary copy that s available only to you for a little while, after you view a report, the Schedule action puts the report instance in history, and these instances are typically available for a much longer time. Scheduling of program objects allows some sort of executable program or script (such as a data warehouse update or CE administrative task done with JScript or VBScript) to be run on a regular recurring basis. The instance, in the case of a scheduled program object, is a text view of the standard and error output from the program object when it runs.

Using scheduled reports has several advantages:

• Scheduling instances can optimize database and network performance by avoiding excess network and database requests .

• The scheduling function provides the ability to enter embedded parameter values, database logon, report format, and/or selection criteria so that viewers aren t prompted for these values.

• Scheduling instances can significantly reduce the time it takes to support a large group of users requesting reports.

So, scheduled instances are flexible and informative while still protecting databases from uncontrolled access, protecting the database servers from unnecessary repetitive queries, and maximizing sharing of common reports.

Note  

The ability to schedule objects is controlled by CE security. Your CE administrator may not have granted you this right for some or all objects. If you don t see the Schedule option in the Web Desktop pop-up menu, check with your CE administrator to see if you have this right.

Scheduling Options

When you schedule an object in Web Desktop, there are several sets of options you must choose from to customize your schedule. These options may vary depending on whether you re scheduling a report or program object, how the report you re scheduling is designed (reports based on secure databases or with parameter fields must have database credentials or parameter values supplied when scheduling), what output destination you want the object sent to, and so forth. And, you have several other scheduling options, such as how many times and when the report should run.

Run-Time Options

The first choice you ll have when scheduling an object is when and how often to run it. These values determine how often and at what time a report instance will be created or a program object will execute. The default option is Now, meaning the object will run immediately. The second option, Once, means it will run only once ”at the time specified and within 24 hours. It defaults to the current time, so accepting the defaults provides an immediate run. The other options run the object regularly at the time specified or based on a calendar that your administrator has defined (calendar-based scheduling is new in CE 10).

Other options include Hourly, Daily, Weekly, Monthly, Nth Day of Month, First Monday of Month, X Day of Nth Week of the Month, Last Day of Month, and Calendar. Once you ve chosen one of the options from the Run report drop-down list, the remainder of the schedule dialog box will change, depending on the first choice you made.

Fill in necessary items for the chosen scheduling interval. Note that you ll often be prompted to specify both starting and ending dates and times. Even if you schedule an object to run, for example, once a day at the current time, you may still be prompted to specify an end time. This comes into play if an object, for some reason, doesn t run at the exact time you specify (perhaps a CE component is down at that time, the object initially fails and needs to be retried, and so forth). By specifying an end time, you ensure that any such schedules will not occur after a point of no return time during the day.

Also, even if you simply choose a regular schedule, such as once per day, you may choose to have the object not run past a particular day. While the default end date is far in the future, you may choose to stop the recurring process at an earlier date.

Scheduling Based on a Calendar

Crystal Enterprise 10 introduces calendar-based scheduling. With this feature, you may simply choose to run an object on specific days defined in one of any number of calendars defined by your Crystal Enterprise administrator. For example, you may find that your particular organization s payroll processing is on a somewhat irregular schedule that the built-in scheduling periods don t quite fit. In these cases, calendars can be defined that identify specific pay days, regardless of holidays, two- or three-payday months, and so forth.

To schedule according to a calendar, choose Calendar from the Run Report drop-down list. A Calendar drop-down list will then appear containing entries for each custom calendar that has been created on the CMS (creating calendars is covered in Chapter 26). Choose the desired calendar. The screen will redraw once again, showing several months in advance with days identified in green acting as days the object will run. Make any desired adjustments to start time, start date, and end date to customize the schedule within the calendar.

Caution  

Make sure you specify other necessary scheduling options from the Customize Your Options drop-down list at the top of the schedule dialog before you click the Schedule icon. If you don t specify all necessary items, the instance will fail or return incorrect results when it is run prematurely.

Database Logon

Depending on the database, or databases, the report you are scheduling is based on, you must specify database credentials as part of the scheduling process (this is not required when scheduling program objects). If proper credentials aren t provided, the instances will fail when they attempt to connect to the database.

Items you may need to specify include the data source name (an ODBC data source, server name , etc.), the database you wish to connect to, the user ID, and password. If there is more than one database, you ll be able to make these choices for each database included in the report. Once you ve specified proper credentials, make sure to click the Update button to save them before proceeding.

Parameter Values

If the report you are scheduling uses Crystal Reports parameter fields, you ll need to supply parameter values in order for an instance to run successfully. Most reports will have default values for parameters, and those defaults may be acceptable to you; if they are, you won t have to change them before scheduling the report. However, if you need different values for this instance, you ll need to supply the new values you wish the instance to use every time it runs.

The parameters displayed will vary, depending on what types of parameters exist on the report you re scheduling. Generally, you ll see each parameter listed with its user prompt, and beneath that you ll see an area for adding values for that parameter. You may be able to choose from a set of possible values from a pick list ”a drop-down list that will show all available values.

Special types of parameters that you should be on the lookout for are date or date/time parameters. These parameter values require adherence to a specific CE format. For example, if you wish to supply a date of January 1, 2002, you can t simply type 1/1/02 or 1/1/2002 ” an error message will appear. You must supply dates in the format Date(yyyy, m, d), including the word Date and the parentheses. So, you would specify a parameter value of January 1, 2002, as Date(2002, 1, 1). Note that a small date picker icon also appears when prompting for a date parameter. If you click this icon and specify a date in the corresponding calendar box, the proper Date(yyyy, m, d) value will be filled in for you.

Note  

If you are scheduling a program object, the Parameters entry will display a single text box where you may specify command-line parameters for the program object.

Filters

Most reports contain a record selection formula that you may wish to modify when scheduling (program objects do not make use of a Filters option). A record selection formula is a Crystal Reports “specific statement that filters database records so that a limited set of data will be included on the report.

You can also modify a group selection formula. A group selection formula is similar to a record selection formula, except that it uses subtotal or summary functions at the end of report groups to limit the report to only groups that contain certain values.

You can modify any existing selection formula this instance uses (either record selection or group selection), as well as adding additional criteria to the formulas. Make sure you supply proper Crystal Reports formula syntax in the selection formula (Record and Group Selection formulas are covered in Chapters 5 and 8).

Note  

If the report s existing record or group selection formulas are based on parameter fields, you need not modify the selection formulas themselves ”the parameter fields will take care of customizing report filtering for you. However, if you do need to modify the selection formulas manually, be careful. Your formulas must strictly adhere to Crystal Reports formula language syntax or the instances will fail.

Destination

By default, the Web Desktop will run a scheduled report against the database, save the set of data returned from the database with the instance, and allow it to be viewed online in one of the report viewers. And, a scheduled program object s standard and error output is saved as a text file, which can be viewed online after the object has run.

However, in the case of report output, you may prefer to have the instance attached to an e-mail message in a different file format (such as Adobe Acrobat format). Or, you might want to save the instance as an Excel .XLS file to a specific location on a LAN server. Or, you might want to send the instance as a Word document to another site via File Transfer Protocol (FTP). Finally, you may simply want the report printed on a printer whenever the instance runs.

If you are in charge of several program objects that, perhaps, perform data warehouse updates or other administrative functions, you may want the standard and error output of the program objects to be e-mailed to you whenever the object runs. Or, you may prefer that the text comprising the object s output be placed in a fixed location on your corporate LAN so that, at any given time, the output from the latest instance of the program object can always be found.

When scheduling, you can specify that Crystal Enterprise send the instance to any number of these destinations. The Destination drop-down allows you to choose Default, Unmanaged Disk, Email (SMTP), or FTP. The Default choice indicates that the instance will be automatically saved on a Crystal Enterprise server with a filename managed by CE. Whenever you view the instance, CE automatically knows where to find the right files for online viewing. The remaining destination choices all produce a set of additional options related to that particular destination, such as e-mail address or specific file location and filename. Consult your Crystal Enterprise administrator for more specific instructions on which destinations are configured on your CE system and what choices you may make for them.

Format

You have a choice of file format when scheduling a report to be e-mailed, FTP ed, or saved to disk (format choices aren t available for program objects). Rather than saving the report in Crystal Reports proprietary .RPT file format, you have a number of format choices, including two Excel formats, Word, Acrobat, and various text formats.

Depending on your format choice, the dialog box will change with prompts for various format-related options, such as page range, how to convert report formatting to spreadsheet formatting, and so forth.

Tip  

Choosing a format other than Crystal Report when using the Default destination will cause different behavior when you attempt to view an instance with a report viewer. Rather than launching the report viewer chosen in Crystal Report Preferences, CE will download the instance in the file format chosen in the Format drop-down list. If a matching application (such as Excel or the Adobe Acrobat Viewer) is installed on your PC, the application will be launched and the instance displayed in that application. Otherwise, you ll be prompted to save the file to disk.

Print Settings

If you are scheduling a report, you may desire that the report simply print on a printer configured on the Crystal Enterprise server (for example, you may migrate mainframe- based production reporting to Crystal Enterprise and wish regular printing jobs, such as invoices and accounts payable checks, to be scheduled by CE).

Regardless of the Destination and Format settings you make, you can choose to print a copy of the report in Crystal Reports format on a printer when the report is run (Print Settings don t apply to program objects). If you check Print a Copy of the Report, the dialog will redraw with additional options, such as a page range and number of copies. You may allow the CE server to use its default printer, or you may specify a printer name (the name you supply must be properly configured or recognized on the CE server ”check with your CE administrator if you re unsure of what printer name to use).

You may also specify different report layout settings, should you wish the report to be printed differently than the layout originally specified when the report was designed. Depending on choices you make from the Set Layout To drop-down list, yet more options will appear in the dialog, allowing you to customize such items as paper size and orientation.

Once you re satisfied with all your various scheduling choices, click the Schedule button in the toolbar. The instance will be submitted to the CMS for scheduling.

The History dialog box will appear showing the newly scheduled instance. Click the Refresh button in the History dialog toolbar to update the status of any scheduled or processing instances. The History dialog box initially shows instances sorted by date/time run in descending (newest to oldest) time. You may alternatively sort instances in ascending date/time order, or in ascending or descending order by the user ID who ran the instance (as noted in the Run By column). Simply click the column heading of the desired sort item ” an up arrow or down arrow will appear next to the column heading, indicating which column instances are currently sorted by, and in what order.

The History dialog will show several different status entries that you may notice:

• Recurring The instance is set up to run on a regular basis, such as every day. When the recurring instance s next run time approaches, the CMS will copy the recurring instance to a new Running instance. By clicking the Recurring status, you can see what the instance s recurrence pattern is and when the next instance is scheduled to run.

• Paused A recurring instance has been paused so that it will not run on its schedule for the time being. A recurring instance can be paused by clicking the check box to the right of a recurring instance and clicking the Pause button above the instance list. To resume a paused instance, check the paused instance and click the Resume button. The Recurring status will reappear.

• Pending The instance is scheduled to run at some point in the future, or is waiting for some sort of dependency to be satisfied (dependencies are discussed in more detail in Chapter 26). Clicking the Pending status will show you the time the instance is scheduled to run, as well as any dependencies the instance is waiting for.

• Running The instance is being processed by the CE server at this time. Clicking the Refresh icon in the History screen toolbar will update the running status as the instance processing progresses.

• Success The instance has completed successfully. By clicking the Success status, you can find out more information about the completed instance.

• Failed The instance failed when it attempted to run. Failed instances can occur for many reasons, such as lack of proper database credentials, failure to supply parameter fields, incorrect database connectivity on the CE server, and so forth. By clicking the Failed status, you ll find out more information on the failed instance, including a description of the reason for the failure (sometimes helpful and descriptive, sometimes not).

To view a successful instance, simply click the date/time entry for the instance. The instance will be displayed in the format chosen when the report was scheduled (to view the latest instance, you can simply choose the View Latest Instance option from the main Web Desktop screen ”you needn t even display the History list first). You may also pause, resume, or delete one or more instances by checking the box to the right of the desired instance or instances and clicking various toolbar buttons above the instance list. Note that rights to pause, resume, and delete instances may be denied to you by the CE administrator.

Scheduling Reports Containing Alerts

Crystal Reports can be designed to make use of report alerts. Report alerts are settings in a report that trigger a red flag when certain conditions are met. Examples would be alerts that would be triggered if sales exceeded a certain goal, customer support calls exceeded a critical level, and so forth (designing Crystal Reports with alerts is discussed in Chapter 9).

When you view a report containing alerts on demand (that is, you simply choose View from the Web Desktop pop-up menu), the report runs just like any other report and alerts are not triggered. However, reports containing alerts behave a little differently when scheduled.

Reports containing alerts will display a special icon in the History list if alerts were triggered when the report ran (you ll notice a small yellow exclamation point added to the report s icon). However, viewing report instances from the History list still will show the entire report, without any indication of what alerts were triggered or what report records triggered them.

However, reports containing alerts will provide an additional option from the main Web Desktop menu. An Alerts option will appear for these reports. Click it to see any report instances that have run that contain triggered report alerts. The report name, as well as instance information, will appear. Additionally, each alert that was triggered (if there is more than one) will appear at the bottom of the report s information. Clicking the report name will simply display the report instance, just as if you would have clicked it in the History list ”no alert information will be displayed. However, clicking an alert name will display the report instance showing only report records that conform to the alert.

Tip  

Crystal Enterprise can also be configured to send an e-mail when a report alert is triggered. This is discussed in Chapter 26.