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
![This figure shows the Report Schedules page. This figure shows the Report Schedules page.](img/schedule-reports.png)
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:
-
Select the New action. The New Report Schedule page appears.
-
Enter the details.
-
Save the changes and exit.
Report Schedule Details Tab
Figure 5-2 Report Schedule Details Page
![This figure shows the Report Schedule Details page. This figure shows the Report Schedule Details page.](img/schedule-details.png)
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 Project & Activity Brief Extract type. The default option is Report. |
Extract Criteria |
If the Report Type is Project & Activity Brief Extract, this field is mandatory, to select a single extract criteria from the Project & Activity Brief Extracts glossary. Otherwise, the field is hidden. |
Extract Criteria Status |
If the Report Type is Project & Activity Brief Extract, this field shows the status of the selected Project & 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 1st and 31st). 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 29th, 30th, or 31st 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 31st from January, in February it will run on 28th (or 29th 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 7th, it will next run on the 7th 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
![New Report Schedule Access Control/Recipients page. New Report Schedule Access Control/Recipients page.](img/schedule-access-control.png)
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
![This figure shows the Report Schedule Filters page. This figure shows the Report Schedule Filters page.](img/schedule-filters.png)
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
![This figure shows the details for editing a report schedule. This figure shows the details for editing a report schedule.](img/schedule-edit-details.png)
Submitting a Schedule
When the required schedule details have been entered, to submit the report to run:
-
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.
-
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: Ingredients Where Used - 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
![This figure shows the Report Schedule History page. This figure shows the Report Schedule History page.](img/schedule-history.png)
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
![This figure shows the Schedule History Details page. This figure shows the Schedule History Details page.](img/schedule-history-details.png)
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 Project & 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 If a report exceeds the maximum
number of permitted rows, the stop |
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
![This figure shows the Schedule History Details Query page. This figure shows the Schedule History Details Query page.](img/schedule-details-query.png)
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
![This figure shows the Report Schedule Schedules page. This figure shows the Report Schedule Schedules page.](img/schedule-schedules.png)
Cancelling a Scheduled Report
To cancel a scheduled report:
-
From the Schedules page, select the Cancel action. A Confirm Cancel dialog box appears.
-
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.
-
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.
-
Consider the portal's data refresh time interval if reporting on data sourced from the data warehouse (see Data Warehouse Facility).
-
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 Brand Compliance. 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.