Kentico CMS 7.0 Developer's Guide

Report subscriptions

Report subscriptions

Previous topic Next topic Mail us feedback on this topic!  

Report subscriptions

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

If a user is interested in the content of a specific report or wants to follow the progress of its data, they can use the subscription feature of the reporting module. Subscribers will regularly receive e-mails with the up‑to‑date status of the given report. This way, users can easily keep track of the data provided by the report simply by checking their e-mail, without having to access the website or its administration interface.




Each report has settings that determine whether subscriptions to it should be allowed. On the General tab of the report editing interface, the Enable subscription checkbox applies to the entire report. The same setting is available when configuring the details of individual components (graphs, tables or values). If both settings are enabled, it is possible to subscribe to specific components. For reports published on the website's pages, subscription also needs to be allowed through the Enable subscription property of the web part or widget used to display the given report.


Additionally, the subscription feature is only available for users who belong to a role that has the Subscribe or Modify permission for the Reporting module.


Subscribing to reports


If all of the conditions above are met, users can subscribe to entire reports displayed in the administration interface by clicking on the NewReportSubscription Subscribe action in the header of the given page. This can either be done on a report's View tab in CMS Desk -> Tools -> Reporting or in any other sections of the UI that provide reports, such as Web analytics.


Subscriptions to individual components can be created by right-clicking on the appropriate item in the report and selecting the Subscribe to option in the offered context menu. This way of subscribing is also available for authenticated users when viewing reports on the live site.




Both of these action open a subscription dialog, where the following details can be configured:


Send to - sets the e-mail address to which the subscription e-mails will be sent. By default, the address of the current user is loaded, but a different one may be specified.

Subject - sets the subject that will be used for the subscription e-mails.

Time range - this setting is only available for reports that offer the possibility of displaying data from a specific time range, selected using From and To parameters, e.g. most web analytics and on‑line marketing reports in the system. Users can choose to either have All available data included in every subscription e-mail, or only a certain range of the most recent data according to the date and time when the e-mail is sent. With the second option, the exact time range can be specified through the Data from last field below.

Sending interval - the interval settings define how often and when exactly the report subscription e-mails should be sent.

Condition - may be used to enter an additional macro condition that must be fulfilled in order for the subscription e‑mails to be sent. You can write any condition according to your specific requirements. For detailed information about macro conditions, please see the Development -> Macro expressions -> Macro conditions topic.

Send only if data found - if checked, subscription e-mails will only be sent if the report contains data at the given time (the subscriber will not receive empty reports).




If the report has any parameters that affect how its data is displayed, the report e-mails will always be sent according to the values set before the subscribe action was used.




Users can cancel their subscription to a report at any time by clicking on the unsubscription link included in every e-mail (when using the default e‑mail template).




The link leads to the ~/CMSModules/Reporting/CMSPages/Unsubscribe.aspx system page, where the user can confirm that they wish to unsubscribe from the given report. The appropriate subscription to be removed is automatically identified using parameters passed in the query string of the link's URL.


Alternatively, users with access to CMS Desk can view their report subscriptions in My Desk -> My profile -> Subscriptions and manually Unsubscribe (Delete) as needed. All report subscriptions created by the current user are listed here, even if the target e-mail address belongs to someone else.




For live site users, the same option can be provided by the My account web part, as long as its Display my subscriptions and Display report subscriptions properties are enabled.


After unsubscribing through any of the described ways, a notification e-mail is automatically sent to the given address.


Managing report subscriptions


When editing a report in CMS Desk -> Tools -> Reporting, it is possible to view and manage all of its subscriptions on the Subscriptions tab. The Edit (Edit) icon can be used to modify the details of existing subscriptions. Individual subscriptions may be manually removed using the Delete (Delete) action and new ones can be added to the report by clicking the NewReportSubscription New subscription button in the tab's header.




Creating or editing a subscriptions here offers the standard subscription dialog as described above, but with several additional options.


The Subscription item selector may be used to choose whether the subscription e-mails should include the full content of the report or only a specific graph, table or value component.


Individual subscriptions may be manually disabled by unchecking the Enabled property.


If the currently edited report has parameters, the Subscription parameters section below the main settings provides a way to enter the values that should be used for the reports sent to the subscriber. Only parameters that are configured to be visible when viewing the report can be edited (i.e. those that have the Display attribute in the editing form checkbox enabled on the Parameters tab).







Time range parameters


Some reports offer the possibility of displaying data from a specific time span selected through parameters (e.g. most web analytics and on‑line marketing reports in the system). This functionality is ensured by two parameters with Column names set to FromDate and ToDate respectively on the Parameters tab.


These two parameters are not displayed in the Subscription parameters section. Instead, subscriptions to reports that contain them provide the Time range and Data from last settings, which may be used to specify the appropriate values.


Every authenticated user may also configure the options described above for their own report subscriptions by going to My Desk -> My profile -> Subscriptions or a page containing the My account web part, and editing (Edit) the appropriate subscription.


Scheduling subscription mailout


To ensure that the report subscription e-mails are sent correctly and at the appropriate time, the system uses a global scheduled task called Report subscription sender. When executed, this task goes through all enabled reporting subscriptions and checks their settings. If the time interval requirements and condition of a subscription are fulfilled, an e-mail with the current content of the given report is sent out.


By default, the task is executed every minute. If necessary, you can change its configuration in Site Manager -> Administration -> Scheduled tasks. However, if you wish to use report subscriptions, the task must always be enabled and scheduled frequently.







To be able to send e-mails, the system needs to be connected to a working SMTP server. To learn how this can be done, please see the SMTP server configuration topic.



E-mail templates


The content of the reporting e-mails sent to subscribers is based on e-mail templates. If you wish to customize the e-mails in some way, you can edit the templates in Site Manager -> Administration -> E‑mail templates. The following templates are available:


Reporting - Subscription template - defines the content of the main subscription e-mails used to send the report status.

Reporting - Subscription confirmation - used for the automatic notification e-mails sent to the recipient when a new subscription is created.

Reporting - Unsubscription confirmation - used for the notifications that users receive after unsubscribing (or when the subscription is removed by an administrator).





Reports in plain text


If your system is configured to send e-mails in plain text format, the content of report subscription e-mails will be limited. In this case, image based graphs are included as attachments and the data from tables is sent in an a CSV file. HTML graphs are not represented at all.


You can choose the preferred e-mail format using the E-mail format setting that can be found in Site Manager -> Settings -> System -> E‑mails.


The following context macros may be used in report subscription e‑mail templates:


{% SubscriptionBody %} - this macro is resolved into the content of the subscribed report or component.

{% DefaultSubscriptionCSS %} - used to add the CSS styles that are required to properly display report content in the e-mail. This should always be included in the <head>/<style> element in the HTML version of the subscription template.

{% ItemName %} - for subscriptions to individual reporting components, this macro resolves into the name and type (graph, table or value) of the given item. In the case of full report subscriptions, it returns an empty string.

{% UnsubscriptionLink %} - generates a link that can be used to cancel the given subscription.


It is also possible to access the following related objects and their properties (e.g. {% Report.ReportDisplayName %} ):


{% Report %} - ReportInfo object representing the report to which the user is subscribed.

{% ReportSubscription %} - ReportSubscriptionInfo object of the subscription for which the e-mail is being sent.