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.

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

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

Unzip the SSMonitor.zip archive to a folder. This article assumes the archive is extracted to C:\Program Files\SSMonitor

Configure the appropriate parameters in an XML file. You can use the supplied config.xml as a template.

To install SMTP.ocx, follow the OstroSoft instructions (reproduced here as a convienience):

download SMTP.zip

unzip SMTP.ocx from it to Windows System directory

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.

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

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.

HTML formatted emails can contain HTML tags in the header & footer, but I haven’t tested that too much.

<?xmlversion="1.0"?><config><!-- UNC path to VSS database journal file --><databasejournalFile="\\MyServer\MySourceSafeShare\VSS-Log\sources.log"monitorPeriodSeconds="30"networkShare="\\MyServer\MySourceSafeShare"networkDrive="S:"networkUser="domain\user"networkPassword="pass"/><!-- SMTP server properties --><smtpserverName="server.mydomain.com"emailSource="SSMonitor@mydomain.com"emailDest="Joe.Developer@mydomain.com,Sue.Developer@mydomain.com,_<BR> 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><patternname="Detect deleted files"eventFilter="deleted,destroyed,purged,created"pathFilter=""emailSubject="WARNING: Stale working folders"emailHeader="<BR>Warning: Critical SourceSafe operations were performed that may <BR>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"/><patternname="Build settings"eventFilter="Checked In"pathFilter="\.ds[wp]$"emailSubject="Build change settings detected"emailHeader="Change in build settings detected. Your "&_<BR> "mileage may vary."
emailFooter=""
reportPeriodMinutes="5"
/>
<patternname="Daily activity"eventFilter=""pathFilter=""emailSubject="Daily activity report"emailHeader="The following SourceSafe changes were detected "&_<BR> "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:

History

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

Share

About the Author

When not riding roller coasters, Doug Schmidt is a developer based in Vancouver, Canada.
He is not the Doug Schmidt, PhD who contributes to the "C++ Report", nor is he the avant garde accordian player Doug Schmidt, nor is he Douglas Schmidt the classical composer. However, he once almost shared a limo with Arnold Schwarzenegger.

I've 'enhanced' the script to also send e-mails for check out changes. In our team the Developers sometimes forget they have something checked out. This tool e-mails the team. This is simply done by using the VSS Automation object and is run at the time that the e-mail is detected that it should be sent. e.g. it scans recursively from the top level all folders and extracts checked out files. This requires SSAPI.DLL (and registered) and SSVB.DLL to be installed on the monitoring PC (VSS DLLs so license required). Note that the pattern matching (regex) still works.

I've added the following XML to the config file (you'll have to code these in)

I still have the same problem when running as NT Service... how did you resolve this?

It works like a beauty when i run it via console.

I have no exp in VBScript.. I dont know how to place, where to place a string to log all the output to a file... i saw a post similar to this but i dont know where to place this in SSMonitor.wsf file..

I ensured that when i have registered all the regedit parameters properly... and they have single slash.. pointing to correct default locations... I can see that srvany.exe runs as a local administrator of the machine.. not sure what is going wrong.. how do i know if at all it is running or not? what do i place in the wsf file to write it to a file?

Also, should i check if cscript.exe should also run when i am running "SSMonitor" service. I can only see that "SSMonitor" is pointing to srvany.exe and i dont see cscript.exe in my process list (show all processes list also)...

Not sure whether srvany.exe is calling cscript.exe with corresponding values (that are nicely present in the registry mentioned above)

When I run the utility in a command prompt (through cscript), it works perfectly. But if I run it as an NT service under a domain account which is also a local admin, then the utility sends out admin mails and the daily consolidated mail. But it does not send out the intermittent mails whenever a change occurs in the journal. Any ideas?

I still have the same problem when running as NT Service... how did you resolve this?

It works like a beauty when i run it via console.

I have no exp in VBScript.. I dont know how to place, where to place a string to log all the output to a file... i saw a post similar to this but i dont know where to place this in SSMonitor.wsf file..

I ensured that when i have registered all the regedit parameters properly... and they have single slash.. pointing to correct default locations... I can see that srvany.exe runs as a local administrator of the machine.. not sure what is going wrong.. how do i know if at all it is running or not? what do i place in the wsf file to write it to a file?

Could anyone plz convert this to c# code and send it across to rush_dmail@yahoo.com
i have not been successful to do so, in my attempt!!!!!!!!!!!!
if u want i could send the one i have(unsuccessfully)done...
and the good news is i don want wid the SMTP server!
u can cut all that part......(just want the journal file entries to be parsed and value to be put in some flat file)

But there is one problem : when you stop the service, it will kill the cmd process but not the cscript. You will have to kill it manually with a program that can kill locked process.
When I launched the command from a console and killed it, it killed both the cmd and cscript program.
I don't know why the service doesn't stop the cscript.exe process. If you have an idee, please keep me informed.

I also made some modifications inside the script to manage both spanish and english langages. I also add a parameter to the command line to define at which byte to start to parse.
If someone is interested... I can post it or mail it

You could change your script to log directly to a file rather than requiring a CMD.exe shell to redirect the StdOut to a file... something like below let's you go either way... then you can just replace all the references to WScript.StdOut with "OutputStream":

it would appear to me that there is no longer an smtp.zip containing the smtp.ocx file anylonger. There is an OSSMTP.zip (with an OSSMTP.ocx file in it). I can not seem to get it to work using this new ocx file. Am I missing something or is this just an incompatability issue?

-- modified at 18:48 Thursday 3rd November, 2005

it never fails once you post a message you figure it out. there is an smtp.ocx file within the ssmonitor folder that I copied to the system dir and reg'd it.

Hi from Madrid, first of all thanks for this great tool!!
Then, I have a problem. My VSS is in spanish and also the journal file... I configured the xml file but it did not catch any event, so I've modified the "Constants (for parsing VSS journal entries)" in the wsf file, translating them into spanish. But it does not work. Here is my journal file:

This is a great utility. However, I found a bit of a bug in the script, whereby VSS users who have their Windows regional settings set to use a delimiter other than the usual forward slash ("/") will cause the script to fail when it goes to parse the event entry from the journal file. I've copied a diff of my patch here...
_____________________________________________________________________________________

Thank you for sharing this tool. I just started managing a set of VSS repositories and have found SSMonitor to quickly meet my needs. I found the documentation easy to follow and the tool easy to implement.

Thank you for your time creating this tool!

The facts expressed here belong to everybody, the opinions to me. The distinction is yours to draw...