Periodic Reports

Periodic Reports

OrderFlow supports a powerful mechanism for reports to be run automatically on a scheduled basis. Reports of this kind are known on the system as periodic reports. They are highly customisable and can be run at different intervals - either hourly, daily, weekly or monthly.

Some examples of the kinds applications that periodic reports support include:

• Automatically running end of day reports such as stock level, deliveries and orders reports. For example, 3PL can use these reports to daily stock and order data to customers, removing the need to generate these reports manually.
• Management reports on warehouse operational performance.
• Automated reports to customer services on returns or stock adjustments.
• Running sanity checks in the background to identify anomalies or errors and sending a follow up notifications to the support team.

A key feature of periodic reports is their ability to be exported. Any periodic report can be set up with an arbitrary number of exports. These exports can be done using a number of mechanisms, including to a folder on the file system, an email to a configurable set of recipients, or a web service call to a remote system.

A periodic report definition can be configured to trigger the automatic execution of multiple reports. These reports can be both built-in reports as well as custom or bespoke reports, described in detail in the Custom Reports chapter.

Periodic Report Configuration

The starting point for setting up a periodic report is identifying an existing report, or creating a new custom report, which provides the data required.

You can view existing periodic reports on the system by navigating to Reports -> Configurations -> Periodic. As with dashboards and other reports, periodic reports can be created from scratch, or cloned from existing reports. You can create a new one from scratch by clicking on New Periodic Report at the bottom of the page. Below is an example of a periodic report configuration:

In the next section we describe some of these fields in detail.

Reference

The name used in other parts of the application to identify the report. Must be a unique value.

Name

The human-readable name of the report. This differs from Reference in that the unique key is used by the application, whereas the report name is designed to be helpful to users.

Description

A description of what the report does, how it is used, its frequency and/or any other pertinent notes corcerning the report.

Multi-report

If this box is ticked, then a single periodic report definition can be backed up by multiple report configurations.

Report Keys

The unique key(s) of the report(s) to be executed on a schedule. These refer to the built-in or custom reports present on the system.

If Multi-report is unticked, the current definition backs only a single report.

Multi-Parameter Name and Multi-Parameter Values

If set, this allows the same report to be run multiple times as part of a single periodic report execution, with the individual values set using the Multi-Parameter Values field passed through with each successive invocation.

Action

This allows the report data to be passed back into the system for further processing. The action field value identifies the processor that is used.

You would not set a value for this field without prior knowledge of what the appropriate value would be.

Item Order

Controls the ordering of the reports run. Reports with a value set for this field are run first, in ascending order.

Frequency Type

Defines how often the report is to be executed - hourly, daily, weekly or monthly. Depending on the interval, the cutover would contain differently formatted values.

From OrderFlow 3.8.0.5, quarter hourly periodic reports are also possible.

A Note on Quarterly Hour Reports

If using quarter hourly reports, be sure that the report execution schedule is sufficiently frequent, for example, every five minutes.

We'd also recommend that you set the report Item Order value to ensure that quarter hour reports are run first.

Cutover

The point in time when the report is to be executed. The format depends on the frequency type:

• quarter hourly: mm , e.g. 12
• hourly: mm , e.g. 45
• daily: HH:mm , e.g. 17:30
• weekly: EEE HH:mm , e.g. Thu 08:55
• monthly: d HH:mm , e.g. 7 12:20

where the following format notation is used:

• HH - hours (0-23)
• mm - minutes (00-59)
• EEE - day of the week (e.g. Mon)
• d - date (depending on the month, 1-28/29/30/31).

If quarter hourly reporting is used, the cutover will need to be set to a value between 0 and 14.

Activated

Determines whether the report is active, i.e. if it is to be executed on a schedule. If the box is unticked, the report can be tested manually to see whether it produces the desired output.

Persist if Empty

Determines whether empty reports should be persisted on the system. For text, CSV and Excel based reports, empty reports typically occur when there are no data is retrieved when generating the report.

Site-specific

Denotes whether the periodic report definition is run once across all site or warehouse, or run potentially multiple times, for each selected site on the system. If ticked, then the definition will be run for each of the user-selected sites. Selecting no sites results in the definition not being invoked.

Scope

Specifies whether the report is run across certain organisation(s), channel(s) or is run globally. If Organisation is selected, periodic reports will be generated separately on a per organisation basis for selected organisations. Similarly, if Channel scope is used, periodic reports will be generated separately per channel, for selected channels.

A Note on Underlying Reports

Note that the report that is used as an underlying report for a periodic report (as per the Report Keys field described in the previous section) needs to observe a couple of important requirements:

• if the data needs to be scoped, it should follow the reserved parameter conventions for the naming of the channel, organisation and site scoped parameters.
• it should have suitably defined date parameters to ensure that date-sensitive data is correctly filtered.

Testing a Periodic Report

Before activating a new periodic report, you can test it to check whether it produces the expected output. Note that in order to test a periodic report configuration, it must be inactive, as described in the previous section.

Once the Activated box has been unticked, a Test configuration link will appear at the bottom of the page. Clicking on it leads to the Test Report Configuration page, shown below.

Clicking on the Test Report Definition button at the bottom of the page will generate the report(s) for this definition. A small information window will then display at the top right corner of the screen, describing the results of the report generation action. Also, a Delete Existing Reports button will appear on the bottom of the page, which can be useful once the reports have been checked and are no longer wanted on the system.

Note that it is not possible to delete reports in this way once the periodic report has been activated.

If any reports were generated, you can view them by navigating to the periodic report search from Reports -> Periodic -> Search. From the Periodic Report detail screen, you can see all details of the generated report and download it and/or view the file content. From this screen you can also trigger the export of the periodic report Periodic report exports are described in the next section.

Activating a Periodic Report

In addition to checking the Activated checkbox whilst editing a periodic report definition, to ensure that a periodic report is run, a schedule handler definition that references the generateReports handler (and, for exports, one that references the exportReports handler) must be active. There is also a flag against every organisation and channel that controls whether schedules and periodic reports are active, so this also needs to be enabled for the required organisation(s) and channel(s).

Export Configuration

A key feature of periodic reports is their ability to be exported. Multiple export configurations can be set for a single periodic report definition. Export configurations can be set up by taking advantage of one of the remote message types enabled for periodic reports. Setup of remote messages is not covered in in this document.

The two most common message types for periodic reports are file system and email. However, HTTP- and FTP-based message types can also be used.

A file system export results in the output of the report into a directory on the file system, often exposed to remote users via FTP or RSync. The target directory and file names are configurable via a Groovy script. File system report exports allow, for example, end of day information on stock levels, orders, deliveries and other data to be made accessible to end users via a file syste based interface.

The email message type, as the name suggests, supports export of the reports in the given format through an email to a specific set of recipients.

Export Type

The mechanism for setting up periodic report export configurations is described next.

To add a new export configuration, from the Edit Periodic Report Configuration page, click on the New Export Configuration button at the bottom of the screen. Unlike reports and dashboards, export configurations cannot be cloned or exported. However, existng export configurations can be updated, and new ones can be created from scratch.

Below is an example of such a configuration:

The details of the periodic export configuration fields are described next.

Report

An read only text field, containing the Name of the periodic report to be exported.

Organisations/Channels

Depending on the periodic report configuration, this field can either be a list of organisations, a list of channels, depending on the Scope of the report, described in the previous section.

If the periodic report's scope is set to Global, this field will be not be present, since the report runs across all channels and organisations. If the scope is either Organisation, or Channel, this field will contain only the entries which are selected in the periodic report configuration.

Message Type

The remote message type to be used for the report.

Export Threshold

Controls whether a generated report is actually exported.

Periodic reports whose result size is less than this threshold value will not be exported. A blank value or zero indicates that the export will always occur. This field is particularly useful for reports that notify for errors; in this case, a typical configuration is to only export the report if it has recorded at least one result.

Folder Path (Template)

A template can be used to define a folder path relative to the base directory for outputting periodic reports. If left blank, the default folder naming convention will be used.

This field provides a relatively simple way to control the output location of file based periodic reports data. An example is shown below which constructs a folder path based on the organisation, channel and formatted timestamp of the periodic report export.

/${organisation.externalReference}/${channel.externalReference}/${timestamp?string('yyyy-MM-dd')}

The second example below constructs a folder path using the site reference and the periodic report ID.

/${site.externalReference}/${periodicReport.id}

The syntax for the templates is the FreeMarker template language, which is used for example in CSV-based custom reports.

This field is currently only supported for file system-based periodic report exports.

File Name (Scriptable)

Optional field that identifies the target file name and path for file-based export reports. Both the path and the file name can be either literal, or scripted. This field is generally not required for HTTP and email based export message types.

If left blank, the default file name convention will be used, which includes the periodic report reference and the report invocation timestamp. Otherwise, the field can be populated with either a literal (fixed) value, or a Groovy script. In both cases, the value should return a file name, optionally prefixed with a relative path. The separator for directories is the character /.

Activated

Indicates whether the current export configuration is enabled.

Exporting Periodic Reports as emails

A periodic report can be exported as email text, or as an email attachment. The email settings for a periodic report can be configured in two ways.

System-wide settings

The OrderFlow periodic.report.customer.email properties are the default settings that will be used for all periodic reports to be exported as emails or email attachments, unless these are overridden by report-specific settings. Setup of these properties is not covered in this document.

Report-specific settings

These are specified on the export definition configuration. Below is an example of an export definition configuration for a periodic report to be exported as an email attachment:

The details of the periodic export configuration email setting fields are described next.

Email From Address

The address to be displayed in the "From" field of the email.

Email Recipients

The addresses to be sent the email.

Email CCs

The addresses to be CC'd the email.

Email Subject (Template)

A template can be used to define the subject of the email. In the example above, the template evaluates to:

eod_orders_daily report for today.

Email Message (Template)

When a report is exported as an email, the email message text will be the contents of the report. However if the report is exported as an email attachment, a template can be used to define the message of the email. In the example above, the template evaluates to:

Attached is the Daily end of day orders report.