5 Scheduling Reports

This chapter describes the process for scheduling a report to run.

Users with the Advanced Reporting User or Advanced Reporting Administrator authority profiles have the ability to schedule a report to run by selecting a report design and choosing its run frequency and recipients. Filtering may also be applied at the point of scheduling the report, to further refine the data contained within the report.

Reporting users may view existing report schedules they are associated with, and can edit those that they have created. Reporting administrators have full access to all report schedules.

KPIs are scheduled in a similar way to reports.

Note:

There are no system delivered report schedules.

To access the Report Schedules, select the Report Schedules option in the Reports navigation menu.

The list of report schedules is displayed, grouped by status. A single Default list view is provided, plus My Report Schedules (those the user has scheduled) and Associated Report Schedules (those the user is a recipient of.) For each schedule, the code, version, description, report type, and scheduled from/to dates are shown.

Figure 5-1 Report Schedules Page

To see the details for a specific schedule, double-click the row. A tab opens with the details. You can also select the View or Edit actions.

Creating a Report Schedule

To create a new report schedule:

1. Select the New action. The New Report Schedule page appears.

2. Enter the details.

3. Save the changes and exit.

Report Schedule Details Tab

Figure 5-2 Report Schedule Details Page

Table 5-1 New Report Schedule Page - Details

Details	Description
Code	Enter a unique uppercase code for this template. Mandatory field.
Version	The version will default to 1. Read-only field.
Status	This will default to Draft. Read-only field.
Description	Enter the description for this schedule in the supported languages. The description for the default language is mandatory.
Report Type	Select whether scheduling a report, a KPI, or a Process & Activity Brief Extract type. The default option is Report.
Extract Criteria	If the Report Type is Process & Activity Brief Extract, this field is mandatory, to select a single extract criteria from the Process & Activity Brief Extracts glossary. Otherwise, the field is hidden.
Extract Criteria Status	If the Report Type is Process & Activity Brief Extract, this field shows the status of the selected Process & Activity Brief Extracts glossary extract criteria. Otherwise, the field is hidden The purpose of this field is to indicate whether the schedule is using the latest version of the criteria, per the Report Design Status field.
Report Design	If scheduling a report, click the icon to select the report design. This field is hidden if KPI is selected as the report type. Mandatory field.
Report Design Status	This indicates whether the schedule is using the latest version of the report design or not. The message Report Design is up to date is shown if the report design has not been changed since it was selected. If the report design has changed, the message A new version of the Report Design is available, please create a new version to get the latest design is shown, in which case a new version of the report schedule should be created to utilize the latest design. This field is hidden if KPI is selected as the report type. Read-only field.
KPI Report	If scheduling a KPI, click the icon to select the KPI report template. This field is hidden if Report is selected as the report type. Mandatory field. Note: If this is changed once the first KPI value has been created, the cumulative result for the KPI may no longer be valid, as it will be a mixture of different measures.

Table 5-2 New Report Schedule Page - Report Schedule

Details	Description
Schedule Type	Select whether the report is to run as a single instance, or on a recurring or periodic schedule. The default option is Single. If set to Single, the report will run once on the specified date and time. In this case, the recurring and periodic fields are hidden. If set to Recurring, the report will run repeatedly on a selected day of the week or day of the month (within a date range if one is specified) at a given time. In this case, the periodic fields are hidden. If set to Periodic, the report will run repeatedly every x weeks or months (within a date range if one is specified) at a given time. In this case, the recurring fields are hidden.
Recurring Frequency	If the schedule type is recurring, select the frequency the report is to be run. The options are to repeatedly schedule the report by days of the week, or by days of the month. The default option is day of the week. The field is hidden unless the schedule type is Recurring.
Day of the Week	If the schedule type is recurring and the recurring frequency is days of the week, select the days of the week on which the report is to run. Mandatory field. The field is hidden unless the schedule type is Recurring and the recurring frequency is days of the week.
Day of the Month	If the schedule type is recurring and the recurring frequency is days of the month, select the days of the month on which the report is to run. Mandatory field. The field is hidden unless the schedule type is Recurring and the recurring frequency is days of the month.
Periodic Frequency	If the schedule type is periodic, select whether the scheduling frequency is by a number of weeks or months. The field is hidden unless the schedule type is Periodic.
Schedule From Date	Pick the first date that the report is to run. If the schedule type is Single, it will only run on this date. The default is the current date. Mandatory field.
Schedule To Date	Optionally pick the last date that the report is to run. The field is hidden if the schedule type is Single.
Schedule Time	Set the time that the report is to run on its scheduled dates. The time may be selected from the picker in half hour intervals, or a precise time can be entered.
Current scheduled report submission	If the report has already been scheduled, this indicates the next time the report will run based on the schedule criteria. Read-only field.

The scenarios catered for by the schedule types are as follows:

Single

The report will just run once - on the specified from date.

Recurring

The report will run repeatedly, either by day of the week or day of the month. At least one day of the week (Monday to Sunday) or day of the month (between 1^st and 31^st). The report will run on the selected days that occur from the start date to the end date (if one has been set), inclusive.

The scheduler takes into account the number of days in the month, and if scheduled to run on the 29^th, 30^th, or 31^st and that date does not exist in a month, it adjusts to the last day of the month. For example, if scheduled to run on the 31^st from January, in February it will run on 28^th (or 29^th if a leap year). When this occurs, however, for subsequent months it will continue to run on the adjusted day of the month.

Periodic

The report will run repeatedly over a set number of weeks or months, such as every 2 weeks or every 3 months. The report will run on the specified start date, repeating thereafter on the same day of the week or month for the selected interval, from the start date to the end date (if one has been set), inclusive.

For example, if set to run every 2 weeks and the first date is a Monday, it will next run on the Monday of 2 weeks hence, or if set to run every 3 months and the first date is the 7^th, it will next run on the 7^th 3 months hence.

For a periodic scheduling by days, the Recurring option by Day of the Week can be used.

Note:

The scheduler handles any necessary conversion to the portal server's time zone, so the report will run at the scheduled date and time in the time zone of the user who scheduled the report.

It should be noted that reports that use the current date to determine whether something is to be reported as due or overdue, the current date is based on the time zone of the server (which should be UTC). For portals that operate across multiple time zones, this should be taken into account when scheduling the time the report is to run.

The field-set, shown in the following table, is hidden if the report type is KPI, as there is no output as such, a single calculated result is written to the database instead.

Table 5-3 New Report Schedule Page - Report Output

Details	Description
Save Output To	Click the icon to select the folder where the report output is to be saved. Mandatory field. See Report Output Folders.
Overwrite Existing Outputs	Select Yes if the generated output is to overwrite any existing output for the same report. The default option is Yes. If set to Yes, the list of report outputs will just contain the latest run of the report, with its run date and time appended to the report name. If set to No, the list of report outputs will contain all runs of the report, each with its run date and time appended to the report name. Note: If Yes and multiple outputs already exist, all existing instances will be removed and replaced by the new output.
Report Output Name	Enter the name the report is to show as when it appears in the report outputs folder. The run date and time will be appended to this name when the report is generated. Mandatory field. Characters that would result in an invalid file name, such as / and \, are not permitted.
Format	Select which format you wish the report to be generated in. More than one option can be chosen. The options are MS Excel (xls), HTML, PDF, Rich Text Format, MS Excel (xlsx) and MS Word (docx).

Access Control/Recipients Tab

This page controls which users have access to the report or KPI output and who will be sent an email with a link when the output is generated.

Figure 5-3 New Report Schedule Access Control/Recipients Page

Table 5-4 New Report Schedule Access Control/Recipients Page

Details	Description
Users	Click the icon to select individual users to be recipients. Select the user's job role to locate them. The list is restricted to those that have access to the Reports module.
User Roles	Click the icon to select job roles for any users with the role to be a recipient.
External Systems	Click the icon to select any external systems that are to have access to a report output using the Report Attachment API.

Filters Tab

Optionally add any filters to be applied to the report schedule. For information about adding filters, see Filters.

Figure 5-4 Report Schedule Filters Page

The Data Source Filters and Report Design/KPI Filters tables show any filters that have been applied to the data source or report design respectively.

If any have been specified as runtime filters, enter the value here, otherwise these tables show as read-only. The runtime filter option is not relevant for report schedule filters.

The filters are applied as any data source filters AND any report design filters AND any report schedule/KPI filters. For date filters, the time-zone of the user who scheduled the report is assumed.

Note:

A snapshot of any filters applied in the associated data source, KPI, or report design is held on the report schedule. If changes are made to the associated filters, a new version of the report schedule must be created.

When a new version of a report schedule is created, its filters are refreshed from the current filters in the associated glossary records (if any).

When at draft status, the Actions menus include a Refresh Report Filters option which will reset the filters that have been derived from the associated data source, KPI, or report design. A confirmation prompt is presented prior to the filters being reset. The values of any runtime filters will be cleared.

Editing a Report Schedule

To edit a report schedule, select the schedule on the Report Schedules page and select the Edit action. The report schedule record opens in edit mode in a new tab.

Report Schedules are maintained like a versioned glossary. When the report schedule is created, it is assigned version 1 and the status will be Draft. At this status, all fields except the code, version, and status may be edited.

Figure 5-5 Report Schedule Details

Submitting a Schedule

When the required schedule details have been entered, to submit the report to run:

1. Select the Activate action. A submission confirmation prompt dialog box appears. It shows when the report will run, based on the schedule details.

   Figure 5-6 Confirm Report Submission

   

   If the portal is operating the Enhanced Access Control (EAC) permissions feature, a check is made to compare any named recipients' EAC Area restrictions to those of the user submitting the report. Table 5-5 indicates the scenarios that would result in the recipient not being permitted to access the report, in which case an exception will be listed in the dialog box.

   Table 5-5 EAC Report Schedule Exception Scenarios

   Scheduler's EAC Areas	Recipient's EAC Areas	Recipient can access the report?
   None	None	Yes
   None	A, B	No
   A, B	None	Yes
   A, B	A, B	Yes
   A, B	A	No
   A, B	C	No
   A, B	A, B, C	Yes

   Also, if the folder was created by a user with EAC Area restrictions, only users with equivalent Area access will have visibility of the folder.

2. To continue the submission, click Ok. To return to the Report Schedule page, click Cancel.

   The report schedule record is saved, the status is set to Active, and the job is submitted to the scheduler job queue.

   When the status becomes Active, the report schedule record becomes read-only. If changes are required, deactivate the schedule and create a new version.

   Note:

   Users with the Oracle Authorized Administrator authority profile can edit the record at any status. Users with the Advanced Reporting Administrator authority profile can edit any draft schedule. Users with the Advanced Reporting User authority profile can edit draft schedules that they have created.

Deactivating the Report Schedule

Use the Deactivate action to deactivate the schedule. The status is changed to De-activated, making it unavailable for scheduling. At this status, no fields may be edited, but the Create New Version action can be used to create a new version at Draft status, with the version automatically incremented by 1.

Any report outputs that have been created by the schedule remain unaffected.

Deleting the Report Schedule

Use the Delete action to delete the schedule. The template may only be deleted if it is not active and has not generated any report outputs.

Report Generation

When the report runs, the following takes place:

• The report is constructed using the associated RTF template. The contents appear in the language/local of the user who scheduled the report, translations being automatically applied to system text and glossary data where appropriate. If language, then for any translations that do not exist, the portal's base language is substituted.

• The report is created in the chosen file formats. The file name is in the format:

  [Report Name] - [YYYY-MM-DD-HH-MM-SS].[File Type]

  For example: Site Audit Summary - 2018-07-27-14-58-21.pdf

• If the user who scheduled the report has EAC Area access control restrictions, they are applied to the data - so the report will only contain data that their EAC Area permits them access to.

• A Report Output record is created containing the report files. The execution date and time is appended to the report output name. See Viewing Reports.

  If the report contains no data, the Report Output record is created, but the actual output file attachment is not created.

• An email with a hyperlink is sent (as BCC) to the recipients (the template is REPORTDELIVERY or KPIDELIVERY for KPIs). The content of the email is based on the recipient's language/locale.

  Note:

  In order to avoid the creation of reports with excessive content, a maximum number of rows is permitted. If the report generation exceeds the 200,000 limit, the report generation is terminated with the error message: Maximum number of permitted report rows exceeded. Please use filters to reduce the size and retry.

• An entry is added to the report schedule's History page.

History Tab

When the report has run, details will appear in the schedule's History page.

Figure 5-7 Report Schedule History Page

The list shows the date and time of the run (most recent first), how long it took to run, the number of results in the report (reports only, not KPIs), who scheduled it, and the status of the job.

Double-click a row in the list to view the full details. The page is read-only.

Figure 5-8 Report Schedule History Details

Table 5-6 Report Schedule History Details

Details	Description
Schedule Code	The code that uniquely identifies the report schedule.
Schedule Description	The name of the report schedule.
Report Name	The name of the generated data extract file.
Report Type	Whether a report, a KPI, or a Process & Activity Brief Extract.
Report Design	The report design that the report is based on.
Ran On	The date and time the report ran.
Duration	The length of time it took to generate the report.
Scheduled By	The name of the user who scheduled the report.
Results	The number of rows that appear in the report. This will be blank if the Report Type is KPI.
Status	The status of the schedule. If the status shows the success icon, it has successfully completed; if it shows the failure icon, an error occurred. If a report exceeds the maximum number of permitted rows, the stop icon is shown.
Failures	In the event of a failure or stoppage, the exception message.

The Query Log page is available to the Report Administrator. It shows the data selection and record count SQL query statements that the report or KPI has applied.

Figure 5-9 Report Schedule History Details - Query Log

Reports that use an API as their data source rather than an SQL query will show the text Queries executed are not available for API-based Reports instead.

Monitoring Scheduled Reports

Once a report is submitted, the user who submitted it, and reporting administrators can monitor its progress, and may cancel the job if necessary.

Schedules Tab

To view the job progress of the scheduled report, open the Schedules page. The page shows the current status of the schedule and a list of any queued or running instances of the report.

There will typically not be more than one entry in this list, if a report is already scheduled and is resubmitted, the existing schedule will be updated with the new date and time.

The list has columns for the scheduled date and time, the name of the user who submitted it, its status, and a sub status. If the job is in progress, the sub status indicates the stage of process, such as:

• Stage 1 of 3: Counting results

• Stage 2 of 3: Processing data

• Stage 3 of 3: Creating output

Figure 5-10 Report Schedule Schedules Page

Cancelling a Scheduled Report

To cancel a scheduled report:

1. From the Schedules page, select the Cancel action. A Confirm Cancel dialog box appears.

2. To continue the cancellation, click Ok. To return to the Schedules page, click Cancel.

   When a report schedule job is cancelled, the job is terminated, or is removed from the scheduler if it has yet to run. The History page will show the status as having been cancelled, and a notification email (the template is REPORT_CANCELLED) is sent to the user who scheduled the report.

3. Click the Refresh icon to refresh the contents if the schedules list.

Report Scheduling Best Practices

Some best practices to consider when scheduling reports are as follows:

• Avoid excessive reports and potential performance issues by planning for the report contents before submitting it to run. Choose the report design and filters appropriate to the required output.

• For reports that run regularly, particularly large reports, where feasible, schedule them to run outside of the usual business hours.

• When setting the schedule time, avoid regular maintenance times, when the server may be being taken down.

• For reports that focus on data at a point in time, take into account that users who enter the data may have their working day in a different time zone.

• Ensure other recipients of the report have permission to access the report and the data therein. Recipients will only be able to view the report output if they are a user of the system with access to the Report module.

  Note that other than any EAC Area restrictions, it is possible for a report to contain data that a recipient would not usually have access to when accessing Supplier Evaluation. For further details on the reporting permissions rules, see Appendix: Permissions.

• Select the report output formats (typically Excel or PDF) that are appropriate to the report type and the recipients. Avoid choosing more formats than are necessary.

• After submitting a report to run, avoid repeatedly resubmitting it while waiting for it to complete. Use the schedule monitoring facility (see Monitoring Scheduled Reports).

• Where it is not necessary to retain previous versions of the report, use the option to overwrite existing report outputs rather than creating a new output each time the report is run.

• Delete report outputs that are no longer required, rather than relying on the automated purging.

• If historic copies of the report are required to be retained, save the report output to a local or network location rather than storing them within the system.