Advanced System Reporter

  0 rating
8/9/2013 1:49:04 AM
8/9/2013 1:49:04 AM
Source: GitHub
Provider: Sitecore

About

It is really easy to install - just get the package from and install it in Sitecore. All the reports are completely configurable and you can also schedule them to be run and emailed to you at regular intervals.


Source available in GitHub.



Documentation

Documentation
  • Documentation > What is the Advanced System Reporter
    What is the Advanced System Reporter
    Sitecore 6 ships with a very useful function called My Locked Items. At times, though, admin users may want to see all locked items, not just those locked by them. I wrote a little application to do just that. Then I thought of making it more generic, so that one could create other type of reports easily. The result is a little framework which allows to create many types of reports in very short time. In this module I provide this framework together with many useful example reports like:

        items modified updated in the last X days
        items that have more than X children
        items that are publishable but either do not exist or have a different version in the web   
           database.
        items that are based on a particular template
        items with validation errors
        which templates have been linked to a workflow
        locked items
        publishable items with broken links
        audit information
        errors in the log files
        items that have stayed in the same workflow state for more than X days 

    and more.

    You can now also parametrise those reports, save them as links in the desktop, export them, or even create a scheduled task that emails some of them automatically. In addition, you can also apply commands to the items reported. 
    0
  • Documentation > Getting Started with ASR
    Getting Started with ASR

    After you have installed the module you will find a new application in the start menu, named Reporter.

    start menu

    You can then select which report you want to run by clicking Open

    report selection

    In some reports you can select some parameters, the whole section can be expanded/collapsed

    report filter

    We can then proceed to Run the report. A dialog window will inform us of the progress.

    Depending on the configuration of the report different details will be shown. When the reported results are items, double clicking on them will open it in the Content Editor.

    The Report can be exported on three different formats export to

    In some of the reports, also certain commands will appear in the button bar.

    unlock or change ownership

    These can be run on the selected items of the report. A little tip: clicking on the border of the first Column Header (so just to the left of the 'I' of Icon in most reports) will invert the selection.

    If one wants to store the current selected report with the parameters selected, it can be done by either:

     creating a desktop icon by clicking desktop link
     saving the report save button Then it will appear as a child of the generic report item when clicking Open.

    One can create a scheduled task to email certain reports at regular intervals Setting up automatic email reports

    1
  • Documentation > Configuring a report
    Configuring a report

    Reports are stored in the /sitecore/system/Modules/ASR/Reports area. Each Report uses at least one scanner and one viewer. Optionally it can also have one or more filters and commands.

    Scanners

    They are responsible of getting the objects shown on the report. They can be items, or any other object. Developers can create their own scanners, or customise the existing ones. They are all defined under /sitecore/system/Modules/ASR/Configuration/Scanners. Each Scanner definition item contains a reference to an assembly and some attributes. These can be hard-coded or parametrised. If they are parameters then they will show in the Configure Report section when opening a report.

    One of the most useful scanners is provided by the QueryScanner class which allows to run a particular Sitecore Query (see All items, Locked Items and many others).

    Filters

    Optionally one or more filters can be added. Any objects returned by the scanners are sent through the filters. Multiple filters are always and together. Filters are defined in the same way as Scanners (a reference to a class, and optional parameters).

    Viewers

    These objects transform the objects returned by the Scanner (and possibly filtered) into columns to be displayed. If using multiple viewers, the results go through each of them in succession, so different viewers can potentially contribute with different columns.

    When dealing with items, one can use viewers based on the ItemViewer class (see for instance the ItemBasic Viewer definition). When using the ItemViewer class one can use the Columns field to select which columns should be displayed using the following interface:

    reporting

    Not only one can choose from predefined columns (corresponding to properties of items, and some standard fields), but one can also type directly in the dropdown to display as a column the value of any field in the item.

    Commands

    By selecting some commands they will appear in the toolbar so they can be applied to the selected objects. Commands are defined in /sitecore/system/Modules/ASR/Configuration/Commands and they use the same syntax as the Sitecore Commands (a string name that is mapped to a class in the commands.config file or through an include file).

    Parameters

    The attributes passed to Scanners, Filters and Viewers, could be static (hard-coded) but also parametrised so they appear in the Configure Report section. To insert parameters they must exist in the /sitecore/system/Modules/ASR/Configuration/Parameters section. Then they are inserted by using their name in between curly braces. For instance in the All items scanner we can see that the Attributes are defined as query={Root}/descendant-or-self::*. That means Root will be replaced by the value specified by the user in the interface.

    Parameter definition items specify the title, the type of control (text, item selector, date, user selector) a default value and some parameters that are sent to the control.

    2
  • Documentation > Advanced Topics
    Advanced Topics

    There are four basic components that can be customised in ASR: Scanners, Filters, Commands and Viewers. First let's explain what each of those are.

    When one runs a report in ASR, the scanners are created. They will return some objects which are optionally sent through the filters, if they all return true for the item it gets added to the list. Viewers will then process those items and convert them to a series of columns for display. A command is a Sitecore Command which can be applied to the selected items.

    There is one further concept in the ASR: Paremeters. These allow the user to select the information to be sent to Scanners, Viewers and Filters through the UI.

    Scanners

    A scanner is just a class that inherits from the ASR.Interface.BaseScanner abstract class, and must implement the following method signature:

    public abstract ICollection Scan();

    Scan will therefore return a collection of objects; those might be items or any other type of objects.

    We need to create a Scanner definition item under /sitecore/system/Modules/ASR/Configuration/Scanners folder and indicate the Assembly, fully qualified name of the class (obviously we need to put the dll in the bin folder!). Optionally we can specify some attributes in the format name=value|name2=value|&...&nameN=valueN which can then be retrieved with the inherited method getParameter(string).

    Filters

    A filter is simply a class that inherits from ASR.Interfaces.BaseFilter and must implement the following method:

    public abstract bool Filter(object element);

    Filter will therefore return return true if the object is to be included in the report.

    We need to create a Filter definition item under /sitecore/system/Modules/ASR/Configuration/Filters folder and indicate the Assembly, fully qualified name of the class (obviously we need to put the dll in the bin folder!). Optionally we can specify some attributes in the format name=value|name2=value|&...&nameN=valueN which can then be retrieved with the inherited method getParameter(string).

    Don't assume the type of the parameter element, sometimes scanners can return heterogeneous collections.

    Commands

    Commands are just standard Sitecore Commands. They are defined under /sitecore/system/Modules/ASR/Configuration/Commands and besides the name of the command and the icon, they just have the command name, the standard way of mapping commands to classes in Sitecore (check the commands.config file under the App_Config folder).

    Of course the recommended way of creating new commands in Sitecore is to create a class inheriting from Sitecore.Shell.Framework.Commands.Command and adding the mapping through an include configuration file. This is standard best practice in Sitecore and outside the scope of this document.

    The checkbox Put single item on command context simply decides whether to create an array with all the selected items, adding the array to the CommandContext and invoke the command once, or just have one item at a time in the CommandContext and invoke the command once per selected item.

    Viewers

    A viewer is just a class that inherits from the ASR.Interface.BaseViewer abstract class, and must implement the following method signature:

    public abstract void Display(DisplayElement dElement);

    Display will therefore receive a DisplayElement object. One of the properties of this object (Element) will be the object it is trying to display, and then it can use the AddColumn method.

    We need to create a Viewer definition item under /sitecore/system/Modules/ASR/Configuration/Viewers folder and indicate the Assembly, fully qualified name of the class (obviously we need to put the dll in the bin folder!). Optionally we can specify some attributes in the format name=value|name2=value|&...&nameN=valueN which can then be retrieved with the inherited method getParameter(string).

    Example of a simple viewer:

    public override void Display(DisplayElement dElement)
        {
          Sitecore.Security.Accounts.User user = dElement.Element as Sitecore.Security.Accounts.User;

          if (user == null) return;

          dElement.AddColumn("Name", user.Name);
          dElement.AddColumn("Display Name", user.DisplayName);
          dElement.AddColumn("Domain", user.Domain.Name);
          dElement.AddColumn("Is Admin", user.IsAdministrator ? "yes" : "no");
        }

    Columns don't need to be hard-coded as they can be passed through attributes. Another alternative is to use the special field Columns defined in the Viewer definition item. Then those values can be retrieved from code using the Columns property. That's how for instance the ItemViewer class receives the list of columns that should add to the report.

    Parameters

    As explained earlier, the attributes to be sent to the basic components (Scanners, Filters and Viewers) can be hard-coded or obtained through user input in the UI. Parameters are indicated using curly braces, and they must be declared in /sitecore/system/Modules/ASR/Configuration/Parameters. The Parameter definition item includes information about the title, the type of control the default value and some extra parameters. There are currently five parameter types.
    Text

    This will simply display as a text box. It does not react to any parameters.
    Date Picker

    It will show a dropdown calendar selector. The selected date is retrieved as a string in the recommended ISO 8601 format.
    User Selector

    It will show a control that allows to select a user by showing the standard Account selection dialog in Sitecore. The filter attribute could be used to restrict which accounts are displayed the possible values are roles and users. So entering the following attribute in the parameter definition item filter=users will not allow to select roles. Right now the user selector only shows accounts from the Sitecore domain.
    Item selector

    It will show a control that allows to select an item. This control admits several parameters:

        root: the item at the top of the selection tree
        folder: the selected item
        displayresult: how the selected item is shown in the textbox to the user. Possible  

           values:ID,Name,  FullPath!
        valueresult: how the selected item is stored and made available as a parameter. Possible values: ID,

           Name, FullPath
        filter: which items to show and allow to select. It folllows the same syntax as the ​TreeList field type in

           Sitecore.

    Dropdown

    It offers the selection of different values in a dropdown. The possible values are created by adding child items to the parameter definition item. The name of the child items will shown in the dropdown, and the content of the value field used as the value of the parameter.

    There is also another available feature when creating parameters. Certain special token replacements can be used as values in the dropdowns and as default values:

        $sc_lastyear
        $sc_lastweek
        $sc_lastmonth
        $sc_yesterday
        $sc_today
        $sc_now
        $sc_currentuser

    All the date tokens are replaced by a ISO formatted string.

    3
  • Documentation > Email Reports
    Email Reports

    This functionality depends on the ​Scheduled Tasks functionality of Sitecore. To have Sitecore automatically email reports follow these steps:

        Make sure you Save a version of the reports you want to email (see Getting Started with the ASR)
        Open the Item under /sitecore/system/Modules/ASR/Email Reports - ASR/Email Reports and Enter the requested info. Make sure you select the reports to be sent. You can enter multiple "To" addresses, comma separated. Make sure the Active checkbox is enabled
        Check the schedule as defined in /sitecore/system/Tasks/Schedules/Email Reports schedule By default it will send it once every day.
        Make sure the Mail Server settings are defined correctly in the Web.config (settings MailServer, MailServerUserName, MailServerPassword and MailServerPort).

    Reports are attached to the email as HTML files.

    4
Back
Release notes
See the release notes for the Advanced System Reporter
Read more Back
Code examples

Solution screenshots(0)

Upload

Reviews (0)

Sort by: Date Most votes
  • Profile Avatar
    [fullName]

    Level: 0

    x0 x0 x0

    [date]

    [title]

    [text]

    Was this helpful?

    0

Comments (0)

Sort by: Date  Most votes

Leave a Comment

Comment must be field in
Post comment
loader

Write a review

Title can't be empty
Review can't be empty
Post review

Download

Title Description Download Action

Add File