Reports and Alerts are the two user-notification mechanisms in AxCMS.net MS. Both are a part of the workflow support. Reports are generated once a day. Sample reports are "Pages created recently" or "Documents waiting to be published". Alerts are generated immediately when a certain action takes place. Sample alert is "Publishing Request" which is triggered every time publishing is requested for any page. Essentially both reports and alerts are lists of objects fullfilling certain criteria. There is a plenty of pre-defined reports and alerts coming with AxCMS.net. As a developer you can create your custom reports and alerts and add them to AxCMS.net. This article helps you to understand reports and alerts architecture and develop your custom reports and alerts.
Base class for the reports is AxReport and for alerts - AxAlert (which derives from AxReport). Both implement IServiceTask interface. It means, they are scheduled as Service Tasks and are executed inside AxCMS.Service. Report subscriptions are stored directly in the AxServiceTask table as recurring tasks (executed every 24h starting with the time of the fist subscription). Alerts subscriptions are stored in the AxUserAlert table. Users subscribes for an alert for some specific category (and its subtree). So it is possible to be immediately informed about important events and don't be over-spammed at the same time. When an alert is triggered, an entry in AxServiceTask is created, which is executed only once.
To subscribe to reports and/or alerts an editor goes to Admin / My Profile and there "Reports & Alerts".
Main differences between reports and alerts are shown in following table:
To create your custom report you do the following:
- Create a class, generating a report (derive it from AxReport)
- Compile the class and put the DLL into bin-folder of AxCMS.net (MS and AxCMS.Service)
- (optionally) Schedule your report execution for certain users programmatically
For more details check this Tutorial about creating custom reports.
AxReport is sent to all subscribed users via email during the AxServiceTask processing. Report will look like an HTML table. It can look something like that:
To create your custom alert you do the following:
- Create a class, generating an alert (derive it from AxAlert)
- Compile the class and put the DLL into bin-folder of AxCMS.net(MS and AxCMS.Service)
- Trigger an alert programmatically
For more details check this Tutorial about creating custom alerts.
Now the same steps in more details.
Creating a class
To create a custom report you need to create a new class and derive from Axinom.AECMS.Reports.AxReport class (you have to reference AxCMS.BL.dll). As a convention, the name of the class should end with "Report", e.g. MyReport. To create a new custom alert your new class have to derive from Axinom.AECMS.Reports.AxAlert. AxCMS.net will discover all classes inherited from AxReport (AxAlert) (via reflection) and show in the Reports & Alerts window.
AxReport (AxAlert is derived from AxReport) class offers many methods which you can override. Main of them are:
public virtual bool IsReportAllowed(AxUser user)
public virtual bool IsRowAllowed(AxUser user, IProtected element)
protected virtual ArrayList FillRows(AxUser user)
protected virtual string GetHeadline()
protected virtual AxReportColumn[] GetColumns()
AxAlert in turn offers some extra properties and methods. Main of them are:
protected AxAlertParameters _alertParams;
public virtual void Trigger(AxUser causingUser, IEnumerable<IClassifiable> elements);
To fill your alert or report with a content you have to override these 3 methods:
GetHeadline - to set the headline for your report.
GetColumns - to define the columns for your report.
FillRows - to get the real data for the report.
You can override IsReportAllowed to control, if a user may get a report or/and IsRowAllowed to include only row into report, which a user may see (e.g. only the pages, which a user can publish).
_alertParams – that property contains parameters for an alert including affected elements.
Trigger – method for triggering an alert
Deploy your code
Compile your class. Copy the DLL, containing your class, into the bin-folder of AxCMS.net (AxCMSweb). It is recommended to do this copy automatically using a script, e.g. PostBuild.build if you are using sample solution from Axinom. Also copy the DLL to AxCMS.net service directory and restart the service.
Assign a User to the new Report or Alert
Users subscribe themselves to Report or Alerts using "Reports & Alerts" window. For Alerts a category needs to be specified (Alert-subsription applies to a certain category).
You can subsribe users to reports programmatically by inserting records into the table AxServiceTask directly.
Triggering an Alert
To trigger your custom alert you need to add a following code to the exact place where alert should be triggered. In following example custom alert name is MyAlert, user should be a person causing the alert (derived from AxUser class, e.g. author of the page/document) and entity is an IClassifiable object or an array of objects. During alert execution a new ServiceTask is added for each of subscribed users.
new MyAlert().Trigger(user, entity);
For example an alert "New Pages" is triggered in the page creation code immediately after the page is created.
Language Issues
You can enable Multilanguage support for the users of your report or alert. If you want to do this, you have to use GetString-method of the ResourceManager, provided by the class AxReport (or AxAlert), on all the strings, that you generate in your class. Example:
protected override string GetHeadline()
{
return this.TranslationManager.GetString("New pages");
}
If you do this, the standard AxCMS.net-technology for Multilanguage-support ("AxLanguage") is applied, the new terms will be extracted into the default language table (CMS_AX) and you can add translation to the other language tables (e.g. CMS_EN, CMS_DE, etc.).
For every user his/her desired language can be set in the field "DefaultLanguage". This field is not available (yet) in the AxCMS.net GUI, but can be set in the database programmatically. For the language 2-letter ISO-code is used (e.g. "en" or "de").