Tutorial: Creating a Custom Report in AxCMS.net

AxReport can be used to notify subscribed users that important information inside system was changed. Report will look like a table (image bellow) and is sent to subscribers by email. Reports have 24 hour execution interval meaning that you will receive a report once per day. In general, AxReport implements IserviceTask interface. That means that reports are sent during service task execution.

Developing your class

Step 1. Creating a class

First of all, to create your custom report 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 AxReport class (Axinom.AECMS.Reports namespace).

public class MyReport : AxReport
{
}

Step 2. Specifying headline

You can specify a headline of your custom report by overriding GetHeadline method.

protected override string GetHeadline()
{
return "My Custom Report";
}

Step 3. Specifying column headers

Basically, report is a table that could have many columns. Now we need to specify headers for those columns. You have freedom to create your own custom column headers that will be displayed in your report. 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 Report 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

The most important method to override is, of course, the FillRows. That method is used to generate rows for your custom AxReport. Reports are sent to users, that are subscibed to it, and that is why method takes AxUser as an input parameter. Report rows should be added to an instance of ArrayList and each report row in turn should be an instance of AxReportRow. You can add several rows to report table. I have used the following code for that method:

protected override ArrayList FillRows(AxUser user)
{
    ArrayList rows = new ArrayList();

    // get 5 latest project entries
    List<Project> projectList = ProjectAdapter.GetNewProjects();

    foreach (Project prj in projectList)
   {
        AxReportRow reportRow = new AxReportRow(prj);
        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 report row for Project nr.: " + prj.ID);
        rows.Add(reportRow);
}

    return rows;

}

Step 6. Customizing Report 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 built 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 AxReport 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 AxReport

2) Build AxCMS.net application

3) Stop your AxCMS.net Service

4) Copy and paste your dynamic-link library (DLL) with your AxReport to AxCMS.net Service directory

5) Run AxCMS.net Service again

Using AxReports

Subscribing to your custom AxReport

To find custom reports AxCMS.net will look through all classes that derive from AxReport and render them to you in UI. That means after your custom AxReport class is deployed into AxCMS.net application and after opening MS part your instance of AxReport will appear on your User Profile page in Properties -> Reports & Alerts... section. Clicking there will popup another window where you can subscribe to reports. On top of the opened window you will see a Reports section. There you can find your custom report name and subscribe to it by selecting a checkbox. After you save your changes a new row is add to AxServiceTask table. Now you need to wait for AxCMS.net service task to accomplish.

Execution

AxReport is sent to all subscribed users via email during the AxServiceTask processing. Report will look like an HTML table. For example in my case the result will look like that: