opReports 3.0 provides a flexible mechanism for scheduling both recurring and one-off reports.
This page documents the various ways of specifying when a report should be generated, and what time frame it should cover.
Some parts of the GUI refer to this feature as 'From Hours' and 'To Hours'. |
opReports can optionally limit the reporting to inside or outside of configurable business hours. This is set up using the properties from and to, which must be integers and which define the start and end of the time frame you are intested in. If no business hours are given then the default is unrestricted, i.e. from = 0 and to = 24.
If from is larger than to, then the meaning is inverted and the time outside of the given period is reported on.
Here are some examples:
| From | To | Explanation |
|---|---|---|
| 4 | 12 | early morning: from 04:00 to 12:00 noon |
| 9 | 15 | from 09:00 to 15:00 in the afternoon |
| 17 | 24 | evening: from 17:00 to midnight |
| 19 | 5 | late night plus early morning: from 19:00 to midnight and from midnight to 05:00 |
| 0 | 20 | from midnight to 20:00 |
| 18 | 17 | anytime but 17:00 to 18:00, ie. midnight to 17:00, 18:00 to midnight |
In opReports versions 3.0.8 and above you may also specify the desired Business Days, independent of any Business Hour selection. This is done using the opreports-cli parameter exclude (or the identically named schedule property). The value of this parameter must be day1-day2, with each day given in its 3-letter abbreviation, e.g. fri-sun.
All days between and including the two listed days will be excluded from the report. The week sorts Monday to Sunday and wraps: exclude=sun-mon covers Sunday and Monday, exclude=sat-tue covers Saturday, Sunday, Monday and Tuesday, exclude=tue-thu covers Tuesday, Wednesday and Thursday and exclude=mon-sun would exclude the whole week.
If necessary the exclude parameter can be used repeatedly and the exclusions will be joined.
Please note that in opReports versions before 3.1.4 only certain reports supported business days filtering.
To define a recurring report schedule you have to provide a frequency property, which defines when the report is to be generated.
The start and end properties are also required, and define the reporting period.
Depending on the frequency, slightly different formats for start and end time of the report period are supported.
| Frequency | Format for Start and End | Explanation | Example |
|---|---|---|---|
| daily | HH:MM:SS HH:MM | 24:00 means the end of the day, and makes sense only as period end. 00:00 means the beginning of the day. Leading zeros can be omitted. | 14:15 23:45 |
| weekly | Wday HH:MM:SS Wday HH:MM | Wday is one of "Mon", "Tue" ... "Sun" (Case-insensitive). Monday is considered first, Sunday last. Start: Sun 14:00, End Wed 17:00 will cover sun, mon, tue, wed; Start: Fri 17:00, End Mon 09:00 will cover fri, sat, sun, mon. | Fri 14:45 |
| monthly | D HH:MM:SS | D is the day of the month, 1..31. -D counts from the end of the month; -1 is the last day of the month, -2 the second to last etc. | 4 17:00 -1 00:00 |
| yearly | M D HH:MM:SS | M is the month number, 1..12. D is the day number, 1..31. | 12 24 19:00 13 31 24:00 |
For scheduled non-recurring reports, the start and end properties must fully describe a date and time for the reporting period.
All the formats described on the Supported Time Formats page are supported here, including the relative formats like "midnight - 14 days".
Relative formats work fine for generating reports on-demand from the GUI (e.g. a report starting "yesterday" and ending "now" will cover precisely the last 24 hours).
However, using relative formats with scheduled one-off reports will likely lead to unexpected behaviour and should thus be avoided.
Overall we recommend that you stick to one of the unambiguous absolute formats like "30-mar-2014 16:31:53" or the ISO8601-style "2015-03-30T16:31:53" for clarity, and only use relative formats for on-demand reports.
Business hours reporting works as described above.