Thursday, July 7, 2016

Alfresco Notification Rules - Alerting Users of New File Uploads



Did you ever want to be alerted when new content is uploaded to a specific folder in Alfresco?  

The Activities Feed is one method that Alfresco uses to notify users about actions that have occurred in Share like file uploads.  These notifications are usually sent out nightly (They are also called Site Activity Notification emails). 

But if you want to know immediately when a specific kind of upload has occurred, a better option might be to create a rule that will automatically send out a notification email when an upload or change has happened to content within the folder that you would like to track.

For example, a folder rule can be created that would alert you on the upload of a document to an Alfresco folder by sending out a notification email to a specified list of people, as shown in the following:


The email informs you of the time of the upload and has a direct link to the document's details page in Alfresco Share.  It's easy to set up a rule that does this.

Before we start, you'll need to have configured Alfresco to be able to send outbound emails.  A description for how to configure that is described here in the Alfresco documentation.

Now, let's look at how to send email notifications.  Within Share, first navigate to the folder that you would like to monitor and for that folder select the action Manage Rules.  This action is visible from either the document library list view or the folder's detailed page view.



From the Manage Rules page, select the New Rule button along the right and the details for a new rule can then be entered in a form as shown here:


It's necessary to give a name to the rule and also to specify what folder action will trigger the rule, any additional criteria for which types of items that will cause the rule to run, and the action that will be performed.  

In the definition shown above, any Microsoft Word document that has a filename that starts with "Status Report" that gets uploaded to this folder will cause the rule to run.  Send email is the action we've selected to perform.  Note that there are some additional options across the bottom.  In this case we've selected that the rule should apply not only to uploads to this folder but to all its subfolders too.

Next to Send email is a button called Message...  Clicking on that button pops up a dialog that has additional information about the recipients and the content of the email that will be sent.
The Select button lets us choose who should receive the email.  Below that, the Subject of the message can be defined.

In this case, the template file called notify_user_email.html.ftl is selected to define the content body of the email that is sent out.  The contents of that file is displayed in the Message area. It works much like how a mail merge document does.  Embedded within this Freemarker file are references to dynamic data that can be inserted into the email body.

This sample email template file selected here comes along with the base install of Alfresco.  To find this template file, navigate through the repository file structure to this folder:
You have the option of just using the sample file, editing it, or creating a totally new template file in this directory.  The syntax used in the file is HTML and Freemarker.  

For example, here is a portion of the sample email template file:

   <div style="font-size: 22px; padding-bottom: 4px;">
      ${person.properties.firstName} 
     <#if person.properties.lastName?exists> ${person.properties.lastName}</#if> 
has added a new content item, ${document.name}, in the ${document.siteShortName!""} site
   </div>
   <div style="font-size: 13px;">
      ${date?datetime?string.full}
   </div>

Here we see some objects that are available to us to that are dynamically evaluated when the rule is run.  These include person, document and date.  But note that the subject line for the email isn't part of the Freemarker template so you can't embed dynamic properties in it.

Some information available for person that can be referenced when creating the template includes the firstName, lastName, and email.  Similarly, there are many properties available for the document.  Also note that an alternative way to reference document properties is like: ${document.properties["cm:name"]}.

That's all that's needed.  After the template is created and the rule is defined, email notifications will begin to be sent as new Word status reports are filed into this folder.


3 comments:

  1. How can I send an Email to the CURRENT user, who ever this is?

    ReplyDelete
  2. That's a good question.
    It doesn't look like it is possible to select the current user with the GUI available from the "send menu" picker.
    An alternative is to instead of using "send email", to select "execute script".

    Create a script in the Data Dictionary > Scripts folder.
    Make sure you set the mimetype for the script to Javascript (via Edit Properties) and also set a title for the script.

    The contents of the script can be as follows.
    Note that the person object should correspond to the current user.

    var mail = actions.create("mail");
    mail.parameters.to = person.properties["email"];
    mail.parameters.subject = "Hello from JavaScript";
    mail.parameters.from = person.properties["email"];
    mail.parameters.template = companyhome.childByNamePath
    ("Data Dictionary/Email Templates/notify_user_email.ftl");
    mail.parameters.text = "some text, in case template is not found";
    mail.execute(document);

    ReplyDelete