SSMonitor - Monitor a Visual SourceSafe database using VBScript

• Download SSMonitor Script - 81 Kb

Introduction to SSMonitor

SSMonitor is a free Windows Scripting utility written to monitor the activity in a Visual SourceSafe journal file. Various event pattern filters can be defined, and email messages can be sent to notify developers when these events occur.

We use SSMonitor to email summary reports of VSS activity every day, and to broadcast significant events (like file deletions or project build setting changes) to all developers. IMHO, these are features that VSS should have had from day one, but don�t get me started. :-)

SSMonitor is designed to be run in a console window on any machine with access to the SourceSafe journal file. No VSS automation component is used, and no VSS license is required. SSMonitor can be run as an NT service.

The first half of this article describes how to install and use SSMonitor, and the second half describes some the VBScript code used to implement SSMonitor.

Part 1 - Installing and using SSMonitor

SSMonitor Features

• Monitors a VSS journal file for user-defined event patterns and sends email notification when events are detected.
• Email can be sent as plain text (ugly) or HTML (less-ugly, big-boned maybe?).
• Events can be filtered by VSS activity (ie. Check ins, moves, etc) and/or by project patterns (ie. "*.cpp" or "\myproject\folder")
• Events can have a report period, to allow multiple similar events to be reported in a single email. This helps cut down on the noise generated by the script.
• Each event definition can have its own destination email addresses if required.
• All of SSMonitor�s configuration data comes from an XML file, which SSMonitor will also monitor while running. If you make changes to the XML file while SSMonitor is running, any cached events are sent out, and the new XML configuration is loaded. No need to shutdown/restart SSMonitor just because you changed a configuration parameter.
• Running SSMonitor.wsf with no command line arguments (cscript.exe SSMonitor.wsf) gives a great big help page. Most of what you need to get going should be found there.
• Adminstrator emails will be sent when certain "significant" events happen:
  • When SSMonitor starts or stops.
  • When SSMonitor reloads its configuration file because it has detected a change.
  • When SSMonitor loses or regains access to the VSS journal file
• SSMonitor can be run as an NT service using the free SRVANY.EXE and INSTSRV.EXE tools from the Windows Resource Kit

Requirements

• Windows Scripting Host 5.6 or later. Tested on Win2K Pro SP3 and XP Pro SP1. If you�re running Win2K or XP, WSH 5.6 is likely already installed.
• Access to a Visual SourceSafe database�s journal file. Your VSS database must be configured to log all activity to a journal file. This is set in the Journal_File= setting of srcsafe.ini. See the VSS documentation for details.
• SSMonitor uses the freeware SMTP control from Ostrosoft, available here. Thanks OstroSoft!

Installation

1. Unzip the SSMonitor.zip archive to a folder. This article assumes the archive is extracted to C:\Program Files\SSMonitor
2. Configure the appropriate parameters in an XML file. You can use the supplied config.xml as a template.
3. To install SMTP.ocx, follow the OstroSoft instructions (reproduced here as a convienience):
   1. download SMTP.zip
   2. unzip SMTP.ocx from it to Windows System directory
   3. run "regsvr32 SMTP.ocx" from command-line

Running SSMonitor as a console app

Just run the script using the console script engine. Make sure you supply the /ConfigFile:yourConfigFile.xml argument. If you don�t, don�t worry, the script will nag at you (and nag, and nag) for all the right parameters. The following command should do the trick.

cscript.exe "C:\Program Files\SSMonitor\SSMonitor.wsf" 
            /ConfigFile:"C:\Program Files\SSMonitor\config.xml"

Running SSMonitor as an NT service

I recommend running SSMonitor as an NT service, but only after you've debugged its configuration and deployment at your site, while running SSMonitor as a console app from an interactive logon account. While SSMonitor does provide a fair bit of notification via email, if your SMTP email configuration has not been tested you'll have no available feedback that the service is misconfigured.

SSMonitor can be run as an NT service (and this is how our team has it currently deployed). The free Windows Resource Kit from Microsoft includes two useful tools to easily enable any console application to run as a service. Unfortunately, the documentation that comes with the Resource Kit for INSTSRV and SRVANY is a bit sparse.

Here is what you need to do:

• Assumption: The SSMonitor.zip archive is extracted to C:\Program Files\SSMonitor
• Assumption: The cscript.exe tool is installed at C:\WINDOWS\system32\cscript.exe
• Assumption: The INSTSRV.EXE and SRVANY.EXE tools are installed at C:\Program Files\Windows Resource Kits\Tools
• Install the SRVVANY program as a service named SSMonitor

  instsrv SSMonitor "C:\Program Files\Windows Resource Kits\Tools\srvany.exe"

• Use REGEDIT to add the startup parameters for SRVANY. This is part that Microsoft forgot to document!

  There are 3 registry keys that need to be added as follows:

  REGEDIT4
  
  [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\SSMonitor\
  Parameters]
  "Application"="C:\\WINDOWS\\system32\\cscript.exe"
  "AppParameters"="C:\\Program Files\\SSMonitor\\SSMonitor.wsf 
                /ConfigFile:C:\\Program Files\\SSMonitor\\config.xml"
  "AppDirectory"="C:\\Program Files\\SSMonitor"
  

Example configuration XML

The example XML file below is the sanitized version of the XML configuration I run on our VSS database. I�ve changed the names of a few servers and email addresses, but otherwise it is verbatim.

This configuration monitors the journal file for three types of events patterns:

• Detect deleted files - Event pattern that watches for any file delete/destroy/purge operations and reports them after 5 minutes. This pattern is useful to warn other developers that their local working folders are now out of date and require a manual fix (ie. The other developers have to go and manually delete the file(s) that were just toasted).
• Build settings - Event pattern that looks for changes to DevStudio .DSP and .DSW files. Again, this pattern helps give other developers a "heads up" that their next build might not work unless they do a fresh get.
• Daily activity report - Event pattern that runs once a day and sends out a list of what changed in the past 24 hours.

Things to note:

• Email headers and footers can span multiple lines. This allows you to format your emails nicely.
• Common email options are specified in the <smtp> node. These settings are the defaults for any patterns, but any pattern can override the defaults if required.
• The message body of the email will always be: <smtp.emailHeader> + <pattern.emailHeader> + all matching events + <pattern.emailFooter> + <smtp.emailFooter>. This format allows the greatest flexibility.
• HTML formatted emails can contain HTML tags in the header & footer, but I haven�t tested that too much.

<?xml version="1.0" ?>
<config>
    <!-- UNC path to VSS database journal file -->
    <database
        journalFile="\\MyServer\MySourceSafeShare\VSS-Log\sources.log"
        monitorPeriodSeconds="30"
        networkShare="\\MyServer\MySourceSafeShare"
        networkDrive="S:"
        networkUser="domain\user"
        networkPassword="pass"
     /> 
    
    <!-- SMTP server properties -->
    <smtp
        serverName="server.mydomain.com"
        emailSource="SSMonitor@mydomain.com"
        emailDest="Joe.Developer@mydomain.com,Sue.Developer@mydomain.com,_
                  Some.Manager@mydomain.com"
        emailHeader=""
        emailFooter="If this email is annoying you, see the adminstrator.

No animals were harmed during the automatic formatting of this message."
        formatAsHtml="1"
        adminEmail="Big.Geek@mydomain.com,Little.Geek@mydomain.com"
    />

    <!-- List of VSS event patterns to monitor -->
    <patterns>
        <pattern
            name="Detect deleted files"
            eventFilter="deleted,destroyed,purged,created"
            pathFilter=""
            emailSubject="WARNING: Stale working folders"
            emailHeader="
Warning: Critical SourceSafe operations were performed that may 
leave your working folders out of date!

Check your working folders to ensure that no stale copies remain.

You have been warned! 

The following files were removed or relocated:"
            emailFooter=""
            reportPeriodMinutes="5"
         />
        <pattern
            name="Build settings"
            eventFilter="Checked In"
            pathFilter="\.ds[wp]$"
            emailSubject="Build change settings detected"
            emailHeader="Change in build settings detected. Your " &_
                        "mileage may vary."
            emailFooter=""
            reportPeriodMinutes="5"
         />
        <pattern
            name="Daily activity"
            eventFilter=""
            pathFilter=""
            emailSubject="Daily activity report"
            emailHeader="The following SourceSafe changes were detected "&_
                        "during the past 24 hours."
            emailFooter=""
            fixedReportTime="9:00 PM"
         />
    </patterns>
</config>

Part 2 - Understanding the SSMonitor code

Background

I wrote SSMonitor because I was mad. Sort of.

I had started work on a multi-site project, with a development team in Boston, and another development team in Vancouver. Because of the geographic separation, our combined team needed some sort of notification tool to let other developers know about important changes to the codebase. I found a pay-ware product on the 'net, and it does everything SSMonitor does, but their pricing was outrageous. For our combined team of 30 developers, they wanted about $2500 for this feature. I couldn't believe it. Their product manager tried to sell me on "all their hours of VSS expertise and the stability of their product" but I just said "Bollocks! I can write something like that in a few hours". I hung up the phone, and about two hours later, I began writing SSMonitor during a 6-hour flight from Boston to Vancouver.

When the plane landed, I had learned enough VBScript to write code could monitor and parse the VSS journal file, and by the next day I had SSMonitor sending emails out the entire team. Did it take more than "a few hours" to write? Of course! I'm a programmer! Did you actually believe my first estimate? Maybe I could have finished the whole project on the flight if the AirBus 320 had a WiFi network and an SMTP server :-) But it still took less time than the $2500 price tag of the pay-ware product, so the economics still made sense. Plus, I now have a reason to post something useful to CodeProject, after years of being a happy CodeProject consumer!

Learning VBScript and Windows Scripting Host

I'm a C++ diehard, but I had done a bit of VB here and there. Sometimes I've even been paid to do it! I had already started using VBScript while setting up the daily build using the excellent VisualBuild Pro tool from Kinook Software. I was pretty sure that I could toss together a VBScript snippet to parse the VSS log file.

I've found VBScript to be a pretty cool power tool, allowing me to create classes of objects much like C++. As SSMonitor was my first significant VBScript project, I'm sure that the code will have a C++ flavour to it. Dunno if that is good or bad. :-)

Visual SourceSafe Journal File Format

Visual SourceSafe can be configured to maintain a journal file of all activity performed on the database. This feature is enabled by setting the Journal_File=myjournalfile.log setting in the database's SrcSafe.ini file.

After each action performed by a VSS client, the client will also append a simple text description of the action to the journal file. Each entry has the following format:

$/SomePath/SomeObjectName.ext
Version: x
User: VssAccountName   Date: mm/dd/yy  Time: hh:mm[ap]
Action
Comment: Comment text
Further comment text follows on subsequent lines
(ends with blank line)

Writing a parser for this simple text format was pretty straight forward, and is handled by the SSMON_CVssJournalParser.Parse( in_strFileName, in_nByteOffset ) method.

Main Monitoring Loop

The main loop for SSMonitor is pretty simple.

• Load all the patterns and parameters from the XML config file. Sub SSMON_LoadConfigFile( ByVal in_strFilename )
• Monitor the databaseSub SSMON_MonitorDb
• Get the current file size of the journal file. Function SSMON_GetFileSize( ByVal in_strFilename )
• Check if the journal file has changed size. If so:
• Parse all the newly added records from the journal file. Sub SSMON_CVssJournalParser.Parse( in_strFileName, in_nByteOffset )
• Compare each newly parsed record against the array of patterns. Any pattern that matches the record caches the record for later emailing.Sub SSMON_CVssJournalParser.ProcessEvent
• Sleep for little while.
• Check all the patterns to see if their time-to-email has expired. Send out any emails as necessary. Sub SSMON_CMonitorPattern.FlushCacheIfExpired( in_smtpServer )
• Lather, rinse, repeat.

History

2002-Sep-01 Initial release (posted elsewhere on the 'net).

2003-May-02 First posting on CodeProject. Now supports fixed time-of-day emails, administrator emails, and multi-format date strings.