Directory Scanner Readme

1. Overview

The Directory Scanner is a configurable script to scan multiple locations for documents that have reached a maximum age. Offending files can then be e-mailed, moved or deleted. Actions are definable per location that is scanned.

A configuration file is used to specify locations and actions to take on them.The script maintains a log file detailing actions taken by the script, how verbose this log file is can be configured (see 1.2 below).

1.1. Initial Configuration

Before you can use the script, you need to create a configuration file. An example file is provided in the 'cfg' directory. You can base your file from this, either copy or rename it to cfg\ds_cfg.ini. A sample e-mail body is included also.

Although the script will run without, your configuration should at minimum have a general section with an administrator e-mail address and SMTP server details to send e-mails from. See 2.1. General Section below.

1.2. Log File Verbosity

The log file verbosity defaults to verbose (3), this will output a few summary lines and 2 lines for each location scanned as well as any actions taken (emails sent, moved/deleted files). Once you are happy with the setup, it is recommended you change this to informative messages (2). If you are having problems, debug messages (4) may help diagnose the problem.

It is not recommended running a log level >2 on unattended systems. While log files will be rotated when they reach the maximum size, there is no restriction on the number of log files. If only a tool existed to remove files after a certain time. :)

The verbosity can be changed at the top of the directory_scanner.vbs file. Locate the line starting with 'CONST DEFAULT_LOG_LEVEL = ' and change the value to one of:

  1. Error messages only
  2. Error and warning messages
  3. Error, warning and informative messages
  4. Error, warning, informative and verbose messages
  5. Error, warning, informative, verbose and debug messages

2. Configuration File

The configuration is loaded from the working directory: cfg\ds_cfg.ini. The format of an ini file is:

[section]
key=value

The configuration file is made up of a special general section and any number of "location" sections. The general section contains script settings, all other sections are treated as location sections. You can add comment lines by starting the line with the # symbol. In-line comments are not supported.

2.1. General Section

The general section is used for setting generic parameters for the script, such as the administrator e-mail and SMTP server details etc.

[general]
admin_email=admin@example.com
log_max_size_kb=1024
smtp_server=smtp.example.com
smtp_port=25
smtp_username=someone@example.com
smtp_password=secret

All keys here are optional. If no SMTP server is specified, no e-mails will be sent, warnings will be written to the log each time an e-mail should be sent.

The admin_email value should be in the format: user1@example.com;user2@example.com;.

2.2. Scan Locations

All other sections are considered a scan location and can be named using characters A-Z, _ and -. The name is only used to identify the location in logs. Duplicate location names are treated as separate locations and scanned independently.

Keys and their values:

Key Req Value
delete_src N 1 will delete any expired files, 0 will leave them.
email_body N Path to a text file containing the e-mail body text, see 2.3 below.
email_from N The sender of the e-mail for expired documents.
email_subject N The subject line for sent e-mails.
email_to N Sends expired files by e-mail to these users, must have SMTP settings in general, if this key is provided, you must also provided email_subject and email_from.
enabled N specifies if this location should be scanned 1 for yes.
max_age_mins Y the maximum age a file can be before it is expired, in minutes.
move_to N A directory path to move expired files to, can be a local (C:\) or UNC path.
scan_path Y A directory path to scan, can be a local (C:\) or UNC path.
throttle_ms N Milliseconds to wait after scanning a file, use this to prevent disk thrashing on large file systems.

Example that will e-mail and move files to a holding area after 60 minutes.

# Moves and e-mails documents older than an hour to the pending deletion folder.
[my_scan_location]
enabled=1
max_age_mins=60
scan_path=\\server1\scan_folder
move_to=\\server1\pending_deletion
email_from=Directory Scanner <noreply@example.com>
email_to=someone@example.com
email_subject=File %FILENAME% has expired.
email_body=cfg\document_body.txt

2.3. E-mail Body & Special Fields

2.3.1. E-mail Body

You can specify a plain text file that will be used as the e-mail body when sending documents. Create the text file anywhere the script can access set the location's email_body key to point to the file: email_body=C:\path\to\file.txt.

2.3.2. Special Fields

The subject line and e-mail body can contain the following special fields. These fields will be replaced at runtime for each file/location.

%FILENAME%
Displays just the filename portion of the file being scanned.

%FILEPATH%
Display the full file path of the file being scanned.

%MAXAGE%
The 'max_age_mins' value for the location being scanned.

%MOVEDEST%
The destination for moved files, excludes filename, use %MOVEDEST%\%FILENAME%.

2.4. Sample Configuration

The example below moves and e-mails documents older than an hour to a holding area where they will remain for 7 days until deletion.

[general]
admin_email=admin@example.com
log_max_size_kb=1024
smtp_server=smtp.example.com
smtp_port=25
smtp_username=someone@example.com
smtp_password=secret

# Moves and e-mails documents older than an hour to the pending deletion folder.
[move_pending_deletion]
enabled=1
max_age_mins=60
scan_path=\\server1\scan_folder
move_to=\\server1\pending_deletion
email_from=Directory Scanner <noreply@example.com>
email_to=someone@example.com
email_subject=Document %FILENAME% has expired.
email_body=cfg\document_body.txt

# Clears items pending deletion after 7 days
[clear_pending_deletion]
delete_src=1
enabled=0
max_age_mins=10080
scan_path=\\server1\pending_deletion

3. Scheduling the Script

Use the Windows Task Scheduler to automate running of the script. Task Scheduler can run the script based on a time schedule or when specific events are logged.

  1. Load Task Scheduler
  2. On the Actions menu, choose 'Create Basic Task'
  3. Give the task a name and description and press 'Next'
  4. Select a schedule to run the task and press 'Next'
  5. Select 'Start a program' and press 'Next'
  6. In 'Program/script' enter: wscript.exe
  7. In the 'Add arguments' box, add the path to the directory_scanner.vbs file followed by //B. If the path has spaces in it, you must wrap the whole path in speech marks, do not include the //B: "C:\Path With Spaces\directory_scanner.vbs" //B
  8. Set the 'Start in' parameter to the directory where the 'cfg' directory and 'logs' directory will be created.
  9. Once created, right-click on the task and choose 'Run' and check the script logs to confirm it has run successfully.
  10. Remember to set the log file level before leaving the script un-attended for long periods. Log files will only grow to a max. size, but there is no limit on the number of log files.

4. Notes

Working Directory

The script operates from the current working directory. This will default to the directory the script is located if double clicked. When run from a command prompt, it will be the current directory.

The script must have write permissions to this directory as it will create a 'logs' directory for the log files here. You can set the working directory by calling the script from a batch file, a Windows shortcut or the Windows Task Scheduler.

Scan order

Locations are scanned in the order they appear in the configuration file.

Self-cleaning log files

If you find log file growth to be an issue, you can use this script against it's own logs directory. To do this, you must be sure your logs will have rotated at least once within the maximum age, if they do not rotate, it will try to delete the file it is writing to. This will not cause the script to stop, but warnings will be written to the log.

The below will keep log files for 90 days and then delete them.

[script_logs]
delete_src=1
max_age_mins=129600
scan_location=logs

Email From

You can specify a name for the sender of e-mails by using the format:

email_from=Sender Name <sender@example.com>

Moving files

If an offending file is set to be moved and a file exists with the same name in the destination directory, the file is not moved and the administrator is e-mailed. This is to prevent data loss. A location setting could be added to overwrite the destination file.

Permission denied errors

Permission denied errors don't necessarily mean a problem with the security permissions. For example if the log file is in use by another process, the script will throw a permission denied error.

SMTP Authentication

During testing, when invalid credentials were supplied for the SMTP login, the CDO message did not throw an error, if no e-mails are being received, check the credentials.

Script exits immediately and the log file doesn't show any activity

If the script exits immediately in batch mode, this means it has encountered an error before it was able to open the log file for writing. In batch mode, no error will be displayed. You must use interactive mode for the script to display an error message. A likely scenario is not having permission to create the 'logs' directory.

To run the script in interactive mode, use the command: wscript directory_scanner.vbs //I

Note: You should not use interactive mode when the script is being run as a scheduled task, use batch mode (//B).