AxAlert is an important part of AxCMS.net notification mechanism. For example you can use AxAlerts to notify all subscribers that some valuable business information in your system was changed. Basically, alert will look like a table (image bellow) and is sent to subscribers by email.
In general, AxAlert class derives from AxReport class and AxReport in turn implement IserviceTask interface. That means that alerts are sent during service task accomplishment. In addition AxAlerts are added to a different database table AxUserAlert, instead of AxServiceTask as it is for AxReports. I will also demonstrate how to subscibe for alerts.
Developing your class
Step 1. Creating a class
First of all, to create your custom alert you need to create a new class for it. New class should have a reference to Axinom.AECMS.Reports namespace.
using Axinom.AECMS.Reports;
Also your new class should derive from AxAlert class (Axinom.AECMS.Reports namespace).
public class MyAlert : AxAlert
{
}
Strictly speaking, this is the only obligatory step to complete.If you create an empty class and trigger this alert (see below), a mail will be generated listing the elements with some default data. But you can customize the appearance of your alert following the subsequent steps.
Step 2. Specifying headline
You can specify a headline of your custom alert by overriding GetHeadline method.
protected override string GetHeadline()
{
return "My Alert";
}
Step 3. Specifying column headers
Basically, our alert content will represent a single row in a table, so now we need to specify headers for columns. You have freedom to create your own custom column headers that will be displayed in your Alert. I have chosen four columns: first column represents an ID of my entry, second can be used for displaying a date of entry creation, third column will be used as a link to my entry and the last column is simply a text description. TranslationManager translates column names regarding to user browser language settings.
protected override AxReport.AxReportColumn[] GetColumns()
{
ArrayList list = new ArrayList();
list.Add(new AxReportColumn(this.TranslationManager.GetString("MyIDColumn")));
list.Add(new AxReportColumn(this.TranslationManager.GetString("MyDateColumn")));
list.Add(new AxReportColumn(this.TranslationManager.GetString("MyEntryName")));
list.Add(new AxReportColumn(this.TranslationManager.GetString("MyText"))); return (AxReportColumn[])list.ToArray(typeof(AxReportColumn));
}
Step 4. Providing Alert with ID and Link columns
This step is optional, but if your Alert contains a column for ID or a column that should be used as a link then you need to override two following properties. Both properties return integer that represents a column index of a link-column or id-column. According to GetColumns method above ID column index is 0 and Link column index is 2. Property LinkColumn is used by the base implementation of GetColumnText to render a hypertext link (see below). To turn off the functionality in the base version of GetColumnText you can set LinkColumn to some non-existing number.
protected override int IDColumn
{
get
{
return 0;
}
}
protected override int LinkColumn
{
get
{
return 2;
}
}
Step 5. Filling rows of Alert table
Most important method to override is the FillRows. That method is used to generate rows for your AxAlert according to alert parameters (AxAlertParameters class). Alerts are sent to users, that are subscibed to certain alert, and that is why method takes AxUser as an input parameter. Alert rows should be add to an instance of ArrayList and each alert row should be an instance of AxReportRow. Alert parameters contain an array of affected elements. Each affected element should implement IClassifiable interface. I will describe how to specify alert parameters later in this tutorial. As for the method itself I have used the code bellow to generate rows:
protected override ArrayList FillRows(AxUser user)
{
ArrayList rows = new ArrayList();
if (_alertParams != null && _alertParams.AffectedElements != null)
{
foreach (AxAlertElement element in _alertParams.AffectedElements)
{
Project prj = ProjectAdapter.Load(element.ID);
AxReportRow reportRow = new AxReportRow(element);
reportRow.Columns.Add(prj.ID);
reportRow.Columns.Add(DateTime.Now.ToString("dd.MM.yyyy"));
reportRow.Columns.Add(prj.Name);
reportRow.Columns.Add("That is my first alert");
rows.Add(reportRow);
}
}
return rows;
}
Step 6. Customizing Alert row
You add the content to your report inside FillRows. GetColumnText is kind of post-processor which allows to change the data after it is added. The base implementation converts the content of the column LinkColumn to a hyperlink. The link points to the detail page in MS and is build automatically. If you are satisfied with the default implementation, don't override this method.
You can turn of the default implementation by either overriding it and letting it empty or just setting LinkColumn to some non-existent number.
You can override GetColumnText and add some custom processing. It could make sense if you have a variety of your custom alerts which all share the same formatting. This formatting can be implemented inside GetColumnText in your base class, making inheriting classes simplier.
Here is how this method could look like:
protected override string GetColumnText(AxReportRow row, int index)
{
string cellText= string.Empty;
if (index == LinkColumn)
{
long projectId = (long)row.Columns[0];
cellText += string.Format("<a href=\"www.mywebsite.com?ProjectId={0}\" >", projectId);
}
if (row.Columns[index] != null)
{
cellText += row.Columns[index].ToString();
}
if (index == LinkColumn)
{
cellText += "</a>";
}
return cellText;
}
Deploying into AxCMS.net
To deploy your custom AxAlert to AxCMS.net application you need:
1) If you have created your class not inside MS part of AxCMS.net application then you need to provide MS part with a reference to a dynamic-link library (DLL) with your custom AxAlert
2) Build AxCMS.net application
3) Stop your AxCMS.net Service
4) Copy and paste your dynamic-link library (DLL) with your AxAlert to AxCMS.net Service directory
5) Run AxCMS.net Service again
Using AxAlerts
Subscibing to your custom AxAlert
To find custom alerts AxCMS.net will look through all classes that derive from AxAlert and render them to you in UI. That means after your custom AxAlert class is deployed into AxCMS.net application and after opening MS part your instance of AxAlert will appear on your User Profile page in Properties -> Reports & Alerts... section. Clicking there will popup another window where you can subscribe to alerts.
Basically, subscription to alerts is category-tree based. For example if you select a certain subtree in category list then you will see only those alerts which are related to categories of that subtree. By selecting root of Categories you will see a full list of Alerts appearing in the right part of section (check image bellow). You will have to select a checkbox with your custom Alert name and save your changes. After that a new row is added to AxUserAlert table in database. Now you are subscribed to your alert.
Triggering AxAlert
After we have created an alert and subscribed to it we need to learn how to trigger it and set parameters there. As you have noticed I have used Project entity (but you can use any other entity) in my tutorial for my custom alert. I have created a new page in MS part that allows me to create new projects and my goal is to trigger an event during new project creation process. To do so I need to add following row there (in my example user is someone who is responsible for a project, and prj is an instance of Project entity):
new MyAlert().Trigger(user, prj);
After the alert is triggered a new row for ServiceTask is created in database. Do not forget to add updated DLLs to your service task directory otherwise it will throw an exception (check Deploying into AxCMS.net section). As soon as the ServiceTask is accomplished you will receive an alert by email.