Plastic SCM email notifications!

Tuesday, October 28, 2014 2 Comments

People love notifications! So let’s add some to Plastic SCM.

This is a DIY project; it’s not something you’ll find built-in with Plastic SCM. I came with this fast solution to get email notifications when certain Plastic SCM operations were triggered. If you want to have built-in notifications in Plastic, you know you can use the uservoice page to vote up for it.
Now, you can download the tool from here.

Triggers

The entry point for third party tools is the trigger system. Using triggers you can hook up important operations and customize their behavior.

I’ll take the following ones to start coding a simple notification center:

  • After-checkin
  • After-mkreview
  • After-editreview
  • After-mklabel

With the four triggers above, I will be able to get an email when a checkin is created, a new code review is created or edited and finally when a new label is created.

The Plastic SCM triggers provide extra information both before the operation is run (before triggers) and after it finished (after triggers). You can review all the details here. Consuming the standard input or reading the trigger environment variables will help you create smarter and customizable notifications, such us getting notified only when the “README.txt” file has been changed at the release branch by a certain user.

This is a high level diagram explaining how the tool works:

The tool

In order to attach the tool to a Plastic SCM trigger you will need to use the “cm mktrigger” command as follows:

cm mktrigger after-mklabel "mklabelnotifier" "C:\triggers\plasticnotifier.exe aftermklabel C:\triggers\mklabel.txt"

You need to specify the trigger type, a name to easily recognize the new trigger and the tool you want to run when the operation is triggered.

The “plasticnotifier.exe” tool only needs two parameters, the first one is the trigger type and then the configurator file for that trigger type.

Configuration files

The source code will understand three different file formats that will serve as an example that you can use to create additional ones.

Mail list

The most basic configuration file is the list of email recipients the trigger will use when fired. It looks like as follows:
developer1@yourCompany.com
developer2@yourCompany.com
admin1@yourCompany.com
This format is valid for the “aftermklabel” trigger. The “AftermklabelTrigger” class will read the entire list and will start sending emails.

Translation file

For some triggers you will need to provide a mechanism to translate the Plastic SCM user and get the email. This file will be used by the “AfteReviewTrigger” class to translate the code review assignee user and obtain the email to send the message.

This is the config file aspect:
dev1;developer1@yourCompany.com
dev2;developer2@yourCompany.com
dev3;developer3@yourCompany.com
Each line has two fields separated by a semicolon; the first one is the Plastic SCM user ID and the
second one the user email. The trigger will create an environment variable with the code review assignee user ID. The “plastic notifier” will use this file to obtain the email to send notifications to.

Complex file

The last file format has several fields and subfields, take the following content as an example:

%_%message%_%
Changeset {0} created with the "{1}" comment.\r\n
Changeset content:\r\n{2}
%_%subscribers%_%
developer1@yourCompany.com;br:/main/experimental;br:/main
admin1@yourCompany.com;*
This file format is used by the “AfterCheckinTrigger” class and has two parts: the message and the subscribers.

The message is the email body that you can customize.

Three extra fields are available for the message: “{0}”, “{1}” and “{2}” will be automatically replaced by the changeset specification, the changeset comment and the files changed. Again this information is provided by the trigger using environment variables and the standard output.

The subscribers part is similar to the “Mailing list” format we explained above, but this one has extra information. After the user mail you can write, separated by semicolons, the branches you are interested on for notifications. Using a star (*) you will get notification for all the checkin operations done in the server. In the example above, the user “developer1” will only get notifications for the /main and /main/experimental branches, but the user “admin1” will get an email for every single checkin done in the server.

Further work

With the tool provided, you can get notifications when:
  • A new label is created.
  • A new code review has been assigned to you.
  • A new checkin in a certain branch has been performed.
But this is just a small preview of what you can get if you continue working. Here come some suggestions:
  • Get an email when permissions are changed.
  • Get an email when somebody tries to remove a repository.
  • Get an email when certain files are changed.
The source code is written in C# but you can grab it and translate it to any other language. You can improve the code and complete it, and, if you do, please don’t forget to share it!

Happy notifying!



2 comments:

  1. Hello,

    How can I do that in "linux" side?

    thanks

    ReplyDelete
    Replies
    1. In exactly the same way, but using a valid linux exe or script, of course :-)

      Delete