Using Triggers to Email a File after Check In

From Seapine Labs

Contents 1 Introduction 2 Prerequisites 3 About the Script 4 Basic Flow of the Script 5 Download the Code 6 About the Trigger 7 Possible Enhancements 8 Disclaimer

[edit] Introduction

This article shows how a simple script can be used to email a copy of a file after it is checked-in. Using a specified token in the check in comments, the script determines whether an email should be sent or not.

Due to the nature of triggers, the script will run for every file that is checked in, so the token should not be passed when a large number of files are checked in at the same time.

This is meant more as a way to send a specific file to a peer for review after a check in without the peer having to go into Surround SCM to retrieve the file.

[edit] Prerequisites

• The trigger was written using Surround SCM 5.0.4.
• The script was written in C# using Visual Studio 2005.
• The script sends the email using the Simple Mail Transfer Protocol (SMTP). Access to an SMTP host will be needed by the script.

I have tested this against an internal corporate SMTP host and also against an ISP's SMTP host.

Depending on the authentication methods allowed by the SMTP host that you use, this may or may not work. The script uses the default authentication method used by the System.Net.Mail.SmtpClient Credentials property.

[edit] About the Script

The script sends one email for every file that is checked in. The script looks for a token in the following format in the check in comments:

<e-mail:e-mailaddress@company.com;{nextaddress}>

So the token may look something like:

<e-mail:joeg@company.com;jimb@abc.org;georgef@xyz.edu>

One email will be sent to all three email addresses. If the script does not find the token, it does not continue. This gives you the option of whether or not to send the email after the check in.

The script uses the Surround SCM environment variables provided by the check in event to know the name of the file, the branch and repository, and the user who performed the event. This information is used to build the subject and body of the email.

[edit] Basic Flow of the Script

1. Comments are retrieved from the check in event. The comments are checked for the specified token. The script ends if it does not find the token.
2. The script looks for the first instances of the "<" and ">" characters to 'substring' the token out of the comments. It is important to note that the script is looking for the first instances of these characters. This means that the token should be the first thing in the comments. If not, any instance a "<" or ">" character in the comments, prior to the token, will break the script.
3. The get command is built. This command is used to get a copy of the file that was checked in so it can be attached to the email.
4. The get command runs, and specifies the destination to be a folder on the server.
5. After the file is retrieved, the email address is identified. The trigger looks for the ";" character in the token to see if there are multiple email addresses. If a ";" character is found, the trigger loops until there are no more ";" characters.
6. As each ";" character is found, anything prior to it is stripped and added to the collection of email addresses.
7. The file which was placed by the get is retrieved from the server and used as the attachment for the email.
8. The email subject and body are built.
9. The from address is set.

After the email is ready, it is sent using the System.Net.Mail.SmtpClient class.

[edit] Download the Code

Click on the following link to download the code.

Download the Code

This is the Visual Studio 2005 C# project. The executable is also in the \bin\Debug folder.

The file will not work out of the box. You must set your SMTP host address and authentication, as well as the address to use as the "From" address in the email. You must also set the Surround SCM Server connection and authentication parameters for the get command.

The code includes comments to help you understand what it is doing and to help you make any modifications.

[edit] About the Trigger

The trigger itself is very trivial. All you need to do is set a trigger to run after a check-in event. The trigger I setup to test this looks like this:

Trigger applies to files in branch [WysiCorp] and in repository [WysiCorp] [recursively] -- after an event on a [Check in] -- Run script located at "D:\DEV_Projects\SendFile\SendFile\bin\Debug\SendFile.exe"

My mainline branch is called "WysiCorp". So this trigger will be fired on any repository, but only on the mainline branch.

[edit] Possible Enhancements

Since this is something I wrote on the side, I did not get very sophisticated. There are some enhancements that could be done but would require more time.

Smarter Parsing Logic

The way the script is currently written, it expects the token to be at the beginning of the comments for parsing out the e-mail addresses. If you include the token at the end of the comments, and there are any "<" or ">" characters before the token, the script will not properly parse the e-mail addresses to send the e-mail to.

Check the Addresses

The script does not check for well-formed e-mail addresses. Another trigger and script could be created to run before the check in event to check for the token. If it finds the token, then it checks the e-mail addresses to make sure they are well-formed. If they are not, it would prevent the check-in with a message. If they are well-formed, it would proceed with the check-in, which would then call the SendFile script.

Single E-mail with Multiple Files

Another idea would be that the script run by the trigger would simply add to a table the file name and the e-mail address to send the file to. Then, another script that would run in the background would check this table every so often. It would then build a single e-mail for each recipient and include all of the files associated with this recipient.

Dynamic E-mail Subject and Body

The token could be expanded to also include a subject and body of the e-mail. This would be included in the comments.

[edit] Disclaimer

This script is provided as is with no guarantees. This is a script that I wrote in my own time as a side project.

This is meant to show how triggers can be used to send a file after it is checked in. The ability to send the file after a check in is not a native feature of Surround SCM.

Seapine Software Technical support can not provide any support or assistance in the deployment of this script.

Seapine's Services department would be happy to provide you with a quote to deploy something similar in your environment.