Subversion Notify is small executable that enables Subversion source control administrators, through a simple configuration file, to be able to control multiple repository paths for all pre- and post-commit hooks, enforcing commit regular expression requirements, integration with bug and task tracking systems and e-mail notification.

Key Features

Control at folder level

By using multiple <RepoPathConfig> elements, you have the granular control to alter the hook checks at any folder level. (Check out the sample SubversionNotify.cfg for set-up examples included in the download package)

Pre-commit checks

Ensure the integrity of your repository by enforcing commit message standards
Restrict the types of files that can be committed (eliminate accidental commits of temporary or developer specific configuration files)
Enforce file type checks - files that can be committed, but require a special commit tag to make sure it's being committed as per your rules
Check against your task tracking/ bug tracking system to ensure it's a valid tracking item and your standards are enforced (no commits against closed bugs for example)

Post-commit processing

Send out clean, HTML formatted e-mails of the files committed, with highlighted differences, to as many recipients as you choose
Customize your e-mail subject to allow for a quick reference, subject check of the committed files
Update your task tracking/bug tracking system

Pre-Prop change hook

If you want to allow property changes after a commit, you can implement pre-change checks to ensure that the proper message data is included to validate the change (a bug number for instance)

User Mapping

A new root level <UserMappings> element added. If your Subversion ID's don't match the user ID in Active Directory, you can use the <UserMapping> sub-elements to match them up and get access to e-mail address and full names right out of AD

Installation – “hooking into Subversion”

Download the latest version of Subversion Notify from SourceForge.net
Unzip the package into the directory of your choice
Copy the included pre-commit.bat, post-commit.bat and pre-revprop-change.bat to the hooks folder of your repository (or repositories, you can configure as many as you want!)
Edit the batch files to correctly reflect the installation location of the SubversionNotify.exe file you just extracted.
Configure the SubversionNotify.cfg file as appropriate (see this later in this manual for quick start examples and detailed implementations). To assist you in creating a well formed XML configuration, the Schema file (SubversionNotifyConfig.xsd is included in the download)

Quick Start

Examples of simple configurations to get you started using Subversion Notify. Before using any of them, make sure you modify at least the SVNConfig element to point to your Subversion installation.

Send an e-mail after commits

The sample configuration below will send an e-mail for all commits made to any repository that is hooked into Subversion Notify. It does not filter by repository, path or file type. For these more advanced features, see the sections for RepoPathConfig, Mailto and Custom Format Tokens. To use this template, be sure to change the MailServer and E-mail address settings.

<?xml version="1.0" standalone="yes"?>
<subversionNotifyConfig xmlns="http://www.mckechney.com/SubversionNotifyConfig.xsd" LoggingLevel="INFO" MaximumEMailSizeInMb="5" MaximumEmailSubjectChars="255">
    
    <SVNConfig ExePath="C:\Program Files\Subversion\bin\svnlook.exe" />

    
    <MailServer Name="smtp.mydomain.com" Username="" Password="" ADGlobalCatalog="mydomain.com" FromAddress="fromaddress@mydomain.com"/>

    
    <RepoPathConfig ControlledPaths="/">
       <MailTo EMailGroupName="Managers"  EMailType="HTML" />
       <MailTo EMailAddress="custom@mydomain.com" EMailType="Custom" CustomSubjectFormat="#user# - #fileNames#" CustomEmailTemplateFile="customemail.txt" />
   </RepoPathConfig>

    <EMailGroup Name="Managers">
        <EMail Address="email3@mydomain.com" />
        <EMail Address="email4@mydomain.com" />
    </EMailGroup>

</subversionNotifyConfig>

Check for a log message prior to allowing a commit

This configuration checks that the user has added a message along with their commit via the CommitRequirements element. If no comment is added, the commit will fail and the user will get the failure message explaining why. This also demonstrates that you can have more than one CommitRequirement element. At least one will need

<?xml version="1.0" standalone="yes"?>
<subversionNotifyConfig xmlns="http://www.mckechney.com/SubversionNotifyConfig.xsd" LoggingLevel="INFO" MaximumEMailSizeInMb="5" MaximumEmailSubjectChars="255">
    
    <SVNConfig ExePath="C:\Program Files\Subversion\bin\svnlook.exe" />

    
    <RepoPathConfig ControlledPaths="/">
       <CommitRequirements>
          
          <CommitRequirement Description="A commit log message is required" Regex="\w"
                  RegexFailureMsg="A commit log message is required. Please enter a log message" RegexIgnoreCase="true" />

<CommitRequirement Description="A longer commit message is required" Regex=".{10}"
                  RegexFailureMsg="A log message of at least 10 characters is required!" RegexIgnoreCase="true" />

       </CommitRequirements>
   </RepoPathConfig>

</subversionNotifyConfig>

Integrate with Bugzilla

This configuration integrates your Subersion with Bugzilla. Assuming the repository is configured with pre-commit processing (see Installation), this configuration will in enforce:

· The commit message includes a “bug tag” ” [Bug ###] (via the the Regex in the CommitRequirement section)

· The bug item is not in the RESOLVED status (via the Bugzilla section DisallowedStatuses sub-element)

When configured with post-commit processing, the bug will be updated with a new public comment with the default update message format (see the Bugzilla section for details)
Before using this, you will want to change the XmlRpcConfig section to match your Bugzilla installation. Note that your username and password can be encrypted using the SubversionNotify.Utility.exe

<?xml version="1.0" standalone="yes"?>

</ItemTrackerRegistration>

<CommitRequirement Description="A commit log message is required" Regex="\[b?u?g? ?#?([0-9]+(?:\s*,?\s*[0-9]+)*)\]"

RegexFailureMsg="A Bugzilla item tag is required for commit. Please reference it via a [Bug ###] tag in your commit message"

RegexIgnoreCase="true" />

</CommitRequirements>

<BugzillaConfig

ItemLinkURL="http://landfill.bugzilla.org/bugzilla-3.2-branch/show_bug.cgi?id={0}"

ItemFindRegex="\[b?u?g? ?#?([0-9]+(?:\s*,?\s*[0-9]+)*)\]" >

<XmlRpcConfig Host="landfill.bugzilla.org" Port="443" Path="bugzilla-3.2-branch"

BugzillaUserId="michael@subversionnotify.com"

BugzillaPassword="baKvK4982FJCavbtvJzsng==" UseSSL="true" />

</DisallowedStatuses>

</BugzillaConfig>

</ItemTrackers>

</RepoPathConfig>

</subversionNotifyConfig>

Custom Format Tokens

Throughout the configuration file, there are opportunities for you to customize the output from the Subversion Notify tool. This is accomplished by using replacement tokens. The list of defined replacement tokens and the content type that will be inserted is as follows:

#user# - the subversion login ID of the user who has made the commit

#userId# - same as above, the login ID of the user
#commitMessage# - the commit message entered for this revision
#revision# - the revision number of the revision just created with the commit
#fileNames# - comma delimited file name list of the files committed (no path information, just file names)
#filesWithPaths# - comma delimited file list with full repository path information
#repoPhysicalPath# - physical repository path that was committed to

#repository# - same as above, the physical repository path.
#date# - date and time of the commit
#controlledpaths# - the list of RepoConfig ControlledPath values that applied for the commit

#itemNumber# - when using an ItemTracker, this is the item number that was found.

General Settings

subversionNotifyConfig (global settings)

Example:

Properties

Mandatory: Yes
Occurrence: Once only

Attributes

This is an attribute off of the root <subversionNotifyConfig> element that will set the amount of logging that will be included in the SubversionNotify.log file.

§ LoggingLevel - optional. Sets the amount of logging that will be included in the SubversionNotify.log file. Allowed values include:
ERROR - this is least verbose level of logging, only recording error and exception messages
INFO - (default if not specified) A good level of logging that adds informational message to the log plus error messages
DEBUG - the most verbose level. Includes all ERROR and INFO messages plus additional messages that are used solely to aid in the testing and debugging of the application.

§ MaximumEmailSizeInMb - optional. Will set the maximum size allowed for the HTML body. If it exceeds this limit, the program will Zip the HTML content and attach it to the e-mail. If even the Zip exceeds the limit, a generic message will be sent, referring the recipient to the Subversion log for details. Decimal value, default is 5.0 for 5Mb maximum size

§ MaximumEmailSubjectChars - optional. Limits the length of the e-mail subject text. Some e-mail clients need this to be set in order to properly display the subject.
Integer value, default is 255 characters.

§ ConcatPreCommitFailures - optional. Determines whether or not the commit will fail upon finding the first pre-commit check failure (when set to false), or continue processing and concatenate the full list if failures that will then be presented to the user (when set to true).
The default it true so that the users can try to correct all the failures before attempting the next commit.

Subversion Executable Path

Purpose:

Sets the path to the Subversion executable. For a standard installation, this will be: C:\program files\subversion\bin\svnlook.exe, however it should be set to the correct path as per the installation.

Hierarchy:

Child of <subversionNotifyConfig>

Example:

Properties

Mandatory: Yes
Occurrence: Once only

Attributes

ExePath - required. Used to set the path of the svnlook.exe

Mail Server

Purpose:

Sets the parameters for the mail server that will be the host for outgoing e-mail messages.

Hierarchy:

Child of <subversionNotifyConfig>

Example:

Properties

Mandatory: Yes
Occurrence: Once only

Attributes

· Name - required. Defines the name of the target mail server.

Username - optional. Sets the user name for the mail server credentials if required for sending mail through the server. Must be used in conjunction with Password. This value can be encrypted using the SubversionNotify.Utility.exe application.
Password - optional. Sets the password for the mail server credentials if required for sending mail through the server, Must be used in conjunction with "Username". This value can be encrypted using the SubversionNotify.Utility.exe application.
ADGlobalCatalog - optional. Defines the Active Directory Global Catalog address that will be queried to try to match a SVN user ID to an e-mail address.
FromAddress - required. Defines the default e-mail "From" Address should the ADGlobalCatalog value be empty and/or no matching e-mail address could be found.
EMailSubjectTag - optional. Sets a default tag added to the subject of all e-mails sent from the system. This is useful when you want to apply a filter to your e-mail client to handle incoming Subversion Notify messages. The default value is "[SVN]". To eliminate the tag, set the value to "".
UseSecureConnection - optional. This allows you to specify that you want to use an SSL connection to connect to the SMTP server to send mail. Default value is false.
Port - optional. Specifies the port you will use to connect to the SMTP server.

Repository Path Control

RepoPathConfig

Purpose

The root element for defining Pre and Post Commit hook configurations. You can define 1-N number of these elements to provide full granular control over your repository.

Hierarchy

Child of <subversionNotifyConfig>

Example

Properties

Mandatory: Yes. At least 1 RepoPathConfig element is required
Occurrence: One or more

Attributes:

** If either of these values is set to DEFAULT, then this configuration will be used if there are no other matches by path and repository. **

ControlledPaths - required. This determines the starting point of the internal logical repository path to be controlled by this configuration element. To control the entire repository with one element, use "/" to define the root.
ControlledRepos - optional. If added, this represents the physical repositories that are to be controlled with this element. To specify control of more than one repository, separate values with a comma. The physical path is defined at the path to the folder that contains the repository folders (conf,dav, hooks, etc).
ExcludeFromPrecedenceFilter – optional. By default, Subversion Notify will select the most specific RepoPathConfig element as the one that will control a commit. For instance, if you have a two RepoPathConfig elements, one with a ControlledPaths value of “/” and one with a value of “/branches”, then a commit of a file to the “/branches” folder, will only use settings from the RepoPathConfig that is set to “/branches”. This is called precedence filtering. If you set the ExcludeFromPrecedenceFilter attribute to true on the config with the “/” setting, then both configurations would be used in the pre and post commit processing. This is useful if you want to have a general e-mail setting but more specific commit requirements for instance.

MailTo

Purpose

Sets the "To" mail target for sending of the post-commit e-mails. There can be 1-N number of MailTo elements.

Hierarchy

Child of <RepoPathConfig>

Example

Properties

Mandatory: No
Occurrence: Zero or more

Attributes

EMailAddress - optional. This sets the e-mail address that should receive the post-commit e-mails. This can consist of a delimited list of e-mail addresses. The allowed delimiters are ,;:|
EMailGroup - optional. Defines which e-mail group should be included in this e-mail. The EMailGroup is defined as a root level <EMailGroup> element and serves as a reusable distribution list. Both the EmailAddress and EMailGroup can be used together. You can also specify more than one group by delimiting the group names with commas (,).
EMailType - required. Defines the type of e-mail that will be sent. Allowed values are: HTML, Simple, Custom. Simple is a text only e-mail. Custom works in conjunction with CustomEmailTemplateFile.
EMailSuppressionChar - optional. A special character or string that if found in the last 10 characters of the commit message will suppress the sending of the e-mail. This is a means to stop the e-mail notices on a per-commit basis.
CustomSubjectFormat - optional. Allows you to define a custom message subject. The default message subject is the first 100 characters of the commit message followed by the revision number in square brackets.
CustomEmailTemplateFile - optional. Works in conjunction with EMailType="Custom". When the type is set to custom, the tool will look for a file with the name specified in the same folder as the SubversionNotify.exe. It will load this file as the e-mail template and apply the token replacements as found from the list below. The resulting text will be the body of the e-mail sent. If the file cannot be found, a Simple e-mail will be sent instead.
NOTE: The custom format tokens for both CustomSubjectFormat and CustomEmailTemplateFile can be found in the Custom Format Tokens section.
FileNameRegex - optional. Sets a regular expression to use to locate a matching file name or folder path in the list of committed files. If this is set and a match is found, then mail will be send to the appropriate recipient(s), otherwise, this will not trigger an e-mail.
RegexIgnoreCase - optional. Determines whether or not the above regular expression matche will be case sensitive or not. The default is true, meaning that case will be ignored and the match will be case-insensitive

Keep in mind that your e-mail client may truncate overly long subject lines. You can use the top level MaximumEmailSubjectChars setting as described in the General Settings section to manually set a maximum length

DefaultLogMessage

Purpose

If no commit message is specified and there are no Commit Requirements specified, this is the message that will be automatically added to the notification e-mail.

Hierarchy

Child of <RepoPathConfig>

Example

Properties

Mandatory: No
Occurrence: Zero or more

Attributes

· Text - required. Sets the default message that will be added to the commit message. The token #user# can be added to insert the user id of the committer

Execute

Purpose

Defines a target external process to run after the commit has successfully passed all requirements and before the notification e-mail has been sent out. The commit will not continue until this process has completed. A non-zero return code will cause the error message to be written to the log file.

Hierarchy

Child of <RepoPathConfig>

Example

Properties

Mandatory: No
Occurrence: Zero or more

Attributes

Application- required. Defines the external process to execute. Note that this process will be run server side and should not require user input.
CommandLine - optional. Sets the command line options for the process. There are a few tokens that can be used to insert information about the commit:
#revision# - the revision number of the commit
#userid# - the Subversion user ID of the committer
#controlledpaths# - the value of the controlledPaths attribute for the parent RepoPathConfig
#repoPhysicalPath# - the physical drive location of the repository that the commit was made for.
FileNameRegex - optional. Sets a regular expression to use to locate a matching file name or folder path in the list of committed files. If this is set and a match is found, the execute command will be processed. If no match is found, the execute will not happen (unless you use the LogRegex as well and a match is found there)
LogRegex - optional. Sets a regular expression to use to locate a match in the commit log message added by the user. If this is set and there is a match, the “execute” will be processed. If no match is found, the execute will not happen (unless you have a FileNameRegex set and a match is found there.
RegexIgnoreCase - optional. Determines whether or not the above 2 regular expression matches will be case sensitive or not. The default is true, meaning that case will be ignored and the match will be case-insensitive

NOTE: If you do not add either regex values, the execute will process be default unless a CommtterExclusion is found (see below)

CommitterExclusions

Purpose

Allows you to configure individual users to be excluded from producing e-mail alerts and/or executing the external process directives as specified in the Execute element(s).

Hierarchy

Child of <RepoPathConfig>

Example

Properties

Mandatory: No
Occurrence: Only 1 element per RepoPathConfig element allowed

Attributes

None

Child Elements

§ CommitterExclude – required (1-n child elements allowed)

Attributes

SvnID- required. Sets the Subversion user ID that is being configured.
CommitterExclusionType- optional. Sets the type of processing exclusion that will be applied for this user. Valid values are: EMail (default), ProcessExecution, EmailAndProcessExecution, None (same as not having element at all).

Commit Requirements

CommitRequirements

Purpose

Defines the section that controls the required format and content of commit messages and file types before the commit can be completed.

Hierarchy

Child of <RepoPathConfig>

Example

Properties

Mandatory: No
Occurrence: Only 1 element per RepoPathConfig element allowed

Attributes

FailureMessage: optional. Sets a default message should the commit fail based on missing requirements and no specific error message was specified.

Child Elements:

CommitRequirement - required. (1-N elements allowed)
FileTypeTagCheck - optional (0-N elements allowed)
FileTypeExclusion - optional (0-N elements allowed)
FolderNameExclusion - optional (0-N elements allowed)

CommitRequirement

Purpose

Defines a commit message requirement either by regular expression match. If there are more than one of these elements specified, only 1 requirement will need to match in order to allow the commit.

Hierarchy

Child of <CommitRequirements>

Example

Properties

Mandatory: Yes
Occurrence: One or more

Attributes

Description - optional but recommended. This should be your documentation for what the requirement this is enforcing
Regex - required. Sets the regular expression that will be used for searching the commit message. If a match is found, it is considered passed for this requirement. If no match is found, the commit will fail.
RegexFailureMessage - optional. Sets an override to the default FailureMessage set in the CommitRequirements element for the primary Regex test. The failure message displayed will be the RegexFailureMsg value concatenated to the description value.
SecondaryRegex - optional. If a pattern for the Regex value is found and this value is specified, a match on this second pattern will be enforced in order to allow the commit to proceed
SecondaryRegexFailureMsg - optional. If set, it provides the text for the failure reason that will be presented back to the committer. The "\n" newline character can be used to create multi-line messages.
RegexIgnoreCase - optional. Boolean to set how the regular expression should pattern match (case sensitive or not). Default is true to ignore case.

FileTypeTagCheck

Purpose

Sets a rule defining the types of files that can only be committed to the repository with a special commit tag. It is designed to remind committers these file types are "special" and should only be committed with full consideration.

Hierarchy

Child of <CommitRequirements>

Example

Properties

Mandatory: No
Occurrence: Zero or more

Attributes

Description - optional but recommended. This should be your documentation for what the requirement this is enforcing
Regex - required. Sets the regular expression that will be used for searching the commit message. If a match is found, it is considered passed for this requirement. If no match is found, the commit will fail.
FileExtension - required.The file extension (with the .) for the type of file that will be looked for in the commit package. If found on one or more of the files being committed, the Regex check will be made.
FailureMessage - optional but recommended. Provides the text for the failure reason that will be presented back to the committer. The "\n" newline character can be used to create multi-line messages.
ContolledActionType- optional. Defines the commit action type (add, update, delete) being performed on the file that will be checked. For instance, you may want to control the commit of a new .resx file, but don't care if one is updated or deleted. In that case you would specify "Add" add the ControlledActionType value. The allowed values are: Add, Update, Delete, AddUpdate, AddDelete, All (default value), UpdateDelete.
RegexIgnoreCase - optional. Boolean to set how the regular expression should pattern match (case sensitive or not). Default is true to ignore case.

FileTypeExclusion

Purpose

Defines file types that are not allowed to be committed to the repository. This is a server side implementation of the "ignore" client property setting.

Hierarchy

Child of <CommitRequirements>

Example

Properties

Mandatory: No
Occurrence: Zero or more

Attributes

Description - optional but recommended. This should be your documentation for what the requirement this is enforcing
FileExtension - optional. Ignored if FileNameRegex value is set. Defined the file extension (with the .) that will be looked for in the commit. If a file with this extension is found, the commit will fail.
FileNameRegex - optional. Defines the regular expression pattern for the file extension that will be used for searching the committed file names. If a file with a matching pattern is found, the commit will fail. The FileNameRegex value takes precedence over the FileExtension if both are specified.
FailureMessage - optional but recommended. Provides the text for the failure reason that will be presented back to the committer. The "\n" newline character can be used to create multi-line messages.
ControlledActionType - optional. Defines the commit action type (add, update, delete) being performed on the file that will be checked. For instance, you may want to control the commit of a files with a name like .~tmp, but don't care if one is updated or deleted. In that case you would specify "Add" add the ControlledActionType value. The allowed values are: Add, Update, Delete, AddUpdate, AddDelete, All(default value), UpdateDelete .
RegexIgnoreCase - optional. Boolean to set how the regular expression should pattern match (case sensitive or not). Default is true to ignore case.

FolderNameExclusion

Purpose

Defines folder paths that if found in the source files being committed, will cause the commit to fail.

Hierarchy

Child of <CommitRequirements>

Example

Properties

Mandatory: No
Occurrence: Zero or more

Attributes

Description - optional but recommended. This should be your documentation for what the requirement this is enforcing
FolderName- optional. Ignored if FolderNameRegex value is set. Defined the folder name that will be looked for in the commit. If a file with a path containing this folder name is found, the commit will fail.
FolderNameRegex - optional. Defines the regular expression pattern for the file extension that will be used for searching the committed file names. If a file with a matching pattern is found, the commit will fail. The FileNameRegex value takes precedence over the FileExtension if both are specified.
FailureMessage - optional but recommended. Provides the text for the failure reason that will be presented back to the committer. The "\n" newline character can be used to create multi-line messages.
ControlledActionType - optional. Defines the commit action type (add, update, delete) being performed on the file that will be checked. For instance, you may want to control the commit of a new files to an obj directory, but don't care if one is updated or deleted. In that case you would specify "Add" add the ControlledActionType value. The allowed values are: Add, Update, Delete, AddUpdate, AddDelete, All(default value), UpdateDelete .
RegexIgnoreCase - optional. Boolean to set how the regular expression should pattern match (case sensitive or not). Default is true to ignore case.

Full Repository Control Elements

These elements set additional control parameters for the entire repository.

Locked Paths

Purpose

Allows your to define one or more repository paths as being closed (locked) against further commits. This useful to prevent accidental commits to retired branches. The LockedPaths element has no attributes defined.

Hierarchy

Child of <subversionNotifyConfig>

Example

Properties

Mandatory: No
Occurrence: Only 1 element per subversionNotifyConfig element allowed

Attributes

None

Child Elements

· LockedPath - required (1 - n child elements allowed)

LockedPath Attributes

RepoPath- required. Defines the path (can be a top level folder or any subfolder) that will no longer accept commits.
ControlledRepos - optional. If added, this represents the physical repositories that are to be controlled with this element. To specify control of more than one repository, separate values with a comma. The physical path is defined at the path to the folder that contains the repository folders (conf,dav, hooks, etc).

User Mappings

Purpose

Defines a mapping between a Subversion ID and an Active Directory account ID. This is useful when your Subversion ID's are not the same as the AD accounts, but you would still like the e-mails to be send "from" the committer's e-mail address.

Hierarchy

Child of <subversionNotifyConfig>

Example

Properties

Mandatory: No
Occurrence: Only 1 element per subversionNotifyConfig element allowed

Attributes

None

Child Elements

§ UserMapping – required (1 - n child elements allowed)

UserMapping Attributes

SvnID - required. Set the
ActiveDirectoryId- required. Sets the mapped AD account

Pre-Property Change Check

Purpose

Defines how a pre-property change hook call should be processed. This is used in conjunction with the "pre-revprop-change.bat" hook batch file.

Hierarchy

Child of <subversionNotifyConfig>

Example

Properties

Mandatory: No
Occurrence: Only 1 element per subversionNotifyConfig element allowed

Attributes

FailureMessage - required. Sets the commit error message that will be received by the user if they fail to meet the change requirements as defined by the child elements

Child Elements

§ PrePropChangeRequirement – required (1-n child elements allowed)

PrePropChangeRequirement Attributes

Description - optional but recommended. This should be your documentation for what the requirement this is enforcing.
Regex - required. Sets the regular expression that will be used for searching the commit message. If a match is found, it is considered passed for this requirement. If no match is found, the commit will fail.
IsBugMatch - optional. Used as a key to determine if the regular expression is looking for a bug id. (Currently not implemented)
RegexIgnoreCase - optional. Boolean to set how the regular expression should pattern match (case sensitive or not). Default is true to ignore case.

EMailGroup

Purpose

Defines a reusable distribution list for e-mail notification. This list usage is set by the <Mailto> element.

Hierarchy

Child of <subversionNotifyConfig>

Example

Properties

Mandatory: No
Occurrence: Only 1 element per subversionNotifyConfig element allowed

Attributes

Name - required. Sets the identifying name of the group. This value is what is matched in the <MailTo> elements'EMailGroup value.

Child Elements

§ Email – required (1-n child elements allowed)

Email Attributes:

Address- required. The e-mail address of the designated recipient.
DisplayName- optional. Option to add the "real" name of the recipient that will appear in an e-mail program's address display.

PreCommitFailureMessage

Purpose

Let administrators get an e-mail whenever a pre-commit check fails. The e-mail includes the DEBUG level logging text related to the attempted commit.

Hierarchy

Child of <subversionNotifyConfig>

Example

Properties

Mandatory: No
Occurrence: Only 1 element per subversionNotifyConfig element allowed

Attributes

None

Child Elements

§ MailTo – required (1-n child elements allowed)

MailTo Attributes

Same as the <MailTo> element used in the <RepoPathConfig> element with the following limitations:

EMailSuppressionChar is not used
EMailType is not used, all e-mails are sent in plain text
CustomSubjectFormat still optional but does not accept #fileNames# or #filesWithPaths# replacement tokens (the file listing is included in the message body)

Item Tracking and Control - General

Summary

Item tracking allows you to integrate with task and bug tracking systems via a simple plug-in style configuration. The tool comes with 3 "out of the box" integrations:

Bugzilla (via the XML-RPC service interface)
HP Quality Center (via direct Oracle database access)
Rally (via their open API web services)

Each integration inherits functionality from the integration base and this functionality is exposed via common XML attributes and elements in each configuration section.

ItemTrackerRegistration

Purpose

Registers the item tracking plug-in with Subversion Notify.

Hierarchy

Child of <subversionNotifyConfig>

Example

Properties

Mandatory: No (Yes, if you plan on integrating an item tracker)
Occurrence: Only 1 element per subversionNotifyConfig element allowed

Attributes

None

Child Elements

§ Registration – required (1-n child elements allowed)

Registration Attributes

ElementName - required. This is the name of the root element that will be found in the <ItemTrackers> element for this item tracker.
AssemblyName - required. The name of the .NET assembly that should be loaded for this item tracker. This assembly must be in the same directory as SubversionNotify.exe

ItemTrackers

Purpose

This is the container element for the registered item tracker base elements.

Hierarchy

Child of <RepoPathConfig>

Example

Properties

Mandatory: No (Yes, if you plan on integrating an item tracker)
Occurrence: One or more

Attributes

None

Child Elements

Any element defined in the ItemTrackerRegistration element (1-n child elements allowed)

ItemFindRegex and ItemLinkURL

Purpose

ItemFindRegex - required. Specifies the regular expression that will be used to search the commit message. If found, it sets the flag that this item tracking integration applies for this commit and the appropriate checks and data retrieval will take place.

ItemLinkURL - optional. The link format to be used when creating the HTML notification message. This will provide a direct hyperlink to the tracking item from the e-mail message. If omitted, no hyperlink is created.

Hierarchy

An attribute of the root integration element. <Bugzilla>, <QualityCenter>, <Rally>

Example

AllowedProducts

Purpose

Provides for a check against the item tracking system to make sure that the commit is allowed against the items specified product/project. If this element is not specified, there is no check against products.

Hierarchy

An attribute of the root integration element. <Bugzilla>, <QualityCenter>, <Rally>

Example

Properties

Mandatory: No
Occurrence: One or more

Attributes

None

Child Elements

· AllowedProduct – mandatory (1-n child elements allowed)

AllowedProduct Attributes:

· Name - required. The name of the product/project that is allowed for the controlled repository path.

DisallowedStatuses

Purpose

Provides for a check against the item tracking system to make sure that the item is not in a prohibited status. If it is found to be in a disallowed status, the commit will fail. If this element is omitted, no status check will be made.

Hierarchy

An attribute of the root integration element. <Bugzilla>, <QualityCenter>, <Rally>

Example

Properties

Mandatory: No
Occurrence: One or more

Attributes

None

Child Elements

· DisallowedStatus –required (1-n child elements allowed)

DisallowedStatus Attributes

Name – required. Name of the status that the user should not be able to commit against
RepoPathException – optional. The repository path that should be an exception to the rule. This can be a delimited list of repository paths.
UserException – optional. User or users that should be allowed to commit to the tracked item, even when it is in the disallowed status. This can be a delimited list of Subversion user ids.

LockedItems

Purpose

Provides a place to always prevent commits against specific items

Hierarchy

An attribute of the root integration element. <Bugzilla>, <QualityCenter>, <Rally>

Example

Properties

Mandatory: No
Occurrence: One or more

Attributes

None

Child Elements

· Item – required (1-n child elements allowed)

Item Attributes

ItemId – required. The number identifier for the item with to prevent commits against

ItemUpdater

Purpose

Allows for updating of the tracker item via whatever method is provided by the particular tracker.

Hierarchy

An attribute of the root integration element. <Bugzilla>, <QualityCenter>, <Rally>

Example

<ItemUpdater IsPrivate="false">
<MessagePattern>
Committed by: #userId#
Commit Message: #commitMessage#
</MessagePattern>
<ItemUpdater>

Properties

Mandatory: No
Occurrence: One or more

Attributes

IsPrivate- optional. If the tracker accommodates it, sets whether the comment update is marked as private or not. The default value is false, making it a public update

Child Elements

· MessagePattern – optional. (1 child elements allowed). This element allows you to specify what will be included in the update message. You can use any text (assuming it is XML compliant) and the replacement tokens defined for the application. If omitted, the default format is:

Revision: #revision# [#repository#]

Commited By: #userId#

Commit Date: #date#

Commit Message: #commitMessage#

File List:

#filesWithPathsAndChangeType#

Item Tracking and Control - Bugzilla

Summary

Bugzilla integration, inherits from the base integration functionality described in the Item Tracking and Control section of the manual. This includes, checking for allowed products/projects, disallowed item statuses, locked items and item updating.

Specific to the Bugzilla plug-in are the <XmlRpcConfig> and <WebProxyCredentials> elements. These configure the XML-RPC service endpoint that will be used to gather data and provide updates into Bugzilla (note: this requires Bugzilla version 3.+) and any credentials needed to go through a web proxy respectively.

Remember to register the plug-in via the <ItemTrackerRegistration> element.

Hierarchy

Child of <ItemTrackers>

Example

</BugzillaConfig>

XmlRpcConfig

Purpose

Manadatory. Configures the XML-RPC service endpoint and credentials required to make connection. This connection is used to retrieve item information from Bugzilla as well as update information on the item

Attributes

· Host – required. The DNS name or IP address of the Bugzilla server. Just enter the value, do not prefix with http://.

· Path – conditionally optional. If your Bugzilla instance is not the root web site, add the remaining path information to the site here. For instance the Bugzilla “landfill” site is in a sub-directory so the values for Host and Path are: Host=”landfill.bugzilla.org” and Path=”bugzilla-3.2-branch”

· Port – optional. The port that Bugzilla is found on. Usually 80 if you connect to the site via http and 443 if you connect via https. Default is 80.

· UseSSL – optional. Sets whether or not the connection uses SSL secure connection to connect to Bugzilla (yes, you need to set this even if you specify a port value of 443). Default is false

· BugzillaUserID – required. The user id/account that you want to use. This account needs to have access to both read bugs as well as add comments to bugs.

· BugzillaPassword – required. The password for the above account

WebProxyCredentials

Purpose

Optional. If you need to connect to Bugzilla through a proxy server that required authentication, you can provide the credentials

Attributes

· ProxyUserId– required. The user ID to be accepted by the Web Proxy for authentication.

· ProxyPassword– required. The password for the above ID.

Item Tracking and Control - Rally

Summary

Rally integration, inherits from the base integration functionality described in the Item Tracking and Control section of the manual. This includes, checking for allowed products/projects, disallowed item statuses, locked items and item notification.

Specific to the Rally plug-in are the ItemType and WorkspaceNameattributes as well as the <WebServiceConnection> elements that are described below.

Remember to register the plug-in via the <ItemTrackerRegistration> element.

Example

</RallyConfig>

RallyConfig

purpose

Sets the attributes that will be used for Rally integration

Hierarchy

Child of <ItemTrackers>

Attributes

· ItemType – required. Sets the item type that will be queried from Rally. The two valid types are Task and Defect.

· WorkspaceName – required. . Sets the name of the Rally workspace that will be queried.

· IncludeParentItemSummary – optional. Sets whether or not the summary text of the parent User Story should be included with the retrieved text of the Rally task or defect. This can be useful if your tasks are fairly generically named. Default it false

WebServiceConnection

Purpose

Required. Defines the parameters that will be used to call the Rally open API web service

Attributes

§ URL - Required. Sets the URL for the Rally web service.

UserName - Required. Sets the user name for the login credentials that will be used in the connection. This value can be encrypted using the SubversionNotify.Utility.exe application.
Password - Required. Sets the password for the login credentials that will be used in the connection. This value can be encrypted using the SubversionNotify.Utility.exe application.

Item Tracking and Control – HP Quality Center

Summary

HP Quality Center integration, inherits from the base integration functionality described in the Item Tracking and Control section of the manual. This includes, checking for allowed products/projects, disallowed item statuses, locked items and item notification. This integration utilized a direct database connection to the Quality Center Oracle database. As such, you need to define the database server connection parameters as well as the "bug" table that should be queried.

Specific to the Quality Center plug-in is the <DbConnection> element and the ItemTableName attribute described below.

Remember to register the plug-in via the <ItemTrackerRegistration> element.

Hierarchy

Child of <ItemTrackers>

Example

</QualityCenterConfig>

QualityCenterConfig

purpose

Sets the attributes that will be used for HP Quality Center integration

Hierarchy

Child of <ItemTrackers>

Attributes

§ ItemTableName - Required. Sets the table name where the tracking items (defects in Quality Center vernacular) are found.

DbConnection

Purpose

Required. Defines the database connection that will be used to connect to the HP Quality Center Oracle database.

Hierarchy

Child of the <QualityCenterConfig> element

Attributes

UserName - Required. Sets the user name for the login credentials that will be used in the connection. This value can be encrypted using the SubversionNotify.Utility.exe application.
Password - Required. Sets the password for the login credentials that will be used in the connection. This value can be encrypted using the SubversionNotify.Utility.exe application.
sid - Required. Sets the sid value that is used to identify the connection parameters via the TNSNAMES.ORA file.

Subversion Notify Utility

Summary

This utility is a very basic tool to create encrypted usernames and passwords that can be used in the Item Tracking and Control integrations. It works by first creating an encryption text file named EncryptionFile.txt that will act as the "key" for the 2-way encryption. It then uses this file for the processing.

This file must be placed in the same directory as SubversionNotify.exe for the tool to be able to decrypt the text. If this file is modified in any way, you will need to re-run the Utility to regenerate the text file as well as the encrypted user names and passwords.

Implementation note:

The utility required the .NET Framework 3.5 to be installed on the running computer.