Folder Agent
User Guide
Table of Contents
Table of Contents ........................................................................................................................................................... 2
Introduction ..................................................................................................................................................................... 1
Installation/Setup .......................................................................................................................................................... 2
Setup Wizard.................................................................................................................................................................... 2
Upgrading.......................................................................................................................................................................... 4
Uninstalling ...................................................................................................................................................................... 4
System requirements ................................................................................................................................................... 5
Tutorial .............................................................................................................................................................................. 6
Folder Monitor ............................................................................................................................................................. 11
Remote Monitor........................................................................................................................................................... 13
Copy File ......................................................................................................................................................................... 15
Move File ........................................................................................................................................................................ 16
Run Program ................................................................................................................................................................. 17
Delete File ...................................................................................................................................................................... 18
Compress ........................................................................................................................................................................ 19
Expand............................................................................................................................................................................. 20
Action List ...................................................................................................................................................................... 21
Log Message .................................................................................................................................................................. 22
Send Mail ........................................................................................................................................................................ 23
Options ............................................................................................................................................................................ 26
Log Window .................................................................................................................................................................. 27
Properties....................................................................................................................................................................... 28
Templates and Filters ................................................................................................................................................ 29
Path................................................................................................................................................................................... 29
Now .................................................................................................................................................................................. 29
UTCNow .......................................................................................................................................................................... 30
Temp ................................................................................................................................................................................ 30
Base_Path ....................................................................................................................................................................... 30
Relative_Path ................................................................................................................................................................ 30
Attributes ....................................................................................................................................................................... 30
Filters ............................................................................................................................................................................... 31
trim ................................................................................................................................................................................... 31
lower ................................................................................................................................................................................ 31
upper ................................................................................................................................................................................ 31
filename .......................................................................................................................................................................... 31
filenamewithoutextension....................................................................................................................................... 31
extension ........................................................................................................................................................................ 31
directory ......................................................................................................................................................................... 31
getmimetype ................................................................................................................................................................. 31
md5 ................................................................................................................................................................................... 31
sha256 ............................................................................................................................................................................. 32
dateformat ..................................................................................................................................................................... 32
User Guide
Folder Agent
Introduction
In this document I will take you through the steps needed to setup and configure Folder
Agent on your own computer. Once you have gone through the tutorial and appropriate
topic guides you should have a good understanding of what you can do with Folder Agent
and how to go about it.
The installation / setup section takes you through the process of installing Folder Agent. If
you have already done this you can skip ahead to the tutorial which takes you through a
simple file archiving application.
Remember if you have any problems using Folder Agent or aren't sure if it can or can't do
something you can always send me an email at support@frogmorecs.com
Page 1
User Guide
Folder Agent
Installation/Setup
Folder Agent requires the Microsoft .Net 4 Client profile, if you don't have this installed
then the setup program will prompt you to install it. It is a recommended item in Windows
update for Windows Vista and 7 and an optional update for Windows XP. Alternatively it is
available for download from the Microsoft web site, just Google for "download .net 4 client
profile".
The installer is available from our web site at www.frogmorecs.com. The download is
works in trial mode for 30 days, then can be converted to a full unlocked version by
applying the key code that is sent to you when you buy Folder Agent.
When you first download the program your web browser may prompt you with a warning
about downloading content from the internet. As long as you only download Folder Agent
from www.folderagent.com you should be safe.
If you are installing on Windows Vista or later, when you first start the installer you will get
a UAC (User Account Control) prompt. You will need to answer "Yes" to continue as Folder
Agent requires administrator rights to install correctly.
Setup Wizard
There are four steps in the setup wizard, you can move from each step to the next with the
Next button. If you cancel at any point all your changes are undone. The first page is an
introduction.
Page 2
User Guide
Folder Agent
The tasks page lets you specify if you want Folder Agent to launch on startup. You will most
likely need to leave this enabled.
Click on the Install button to complete the installation.
Page 3
User Guide
Folder Agent
After installation has completed a confirmation window is displayed and you have the
option to start Folder Agent when you finish.
Folder Agent installs into the "Progam Files" folder on both 32 and 64 bit systems, usually
this will be C:\Program Files.
Upgrading
To upgrade to a new version of Folder Agent just download and run the latest setup
program from www.folderagent.com. The setup will remember your old settings; the whole
process should be transparent. To avoid a reboot make sure you quit from Folder Agent if it
is already running.
Uninstalling
To uninstall Folder Agent on Windows XP launch the Control Panel and select the Add /
Remove Programs applet.
To uninstall Folder Agent on Windows Vista or Windows 7 launch the Programs and
Features application from the Start menu.
Page 4
User Guide
Folder Agent
System requirements
Supported operating systems:
o
o
o
o
o
o
o
o
o
o
Windows XP SP3
Windows Server 2003 SP2
Windows Vista SP1 or later
Windows Server 2008 (not supported on Server Core Role)
Windows 7
Windows Server 2008 R2 (not supported on Server Core Role)
Windows 7 SP1
Windows Server 2008 R2 SP1
Windows 8
Windows Server 2012
Supported Architectures:
o x86
o x64
Hardware Requirements:
o Recommended Minimum: Pentium 1 GHz or higher with 512 MB RAM or
more
o Minimum disk space:
x86 – 600 MB
x64 – 1.5 GB
Prerequisites:
o Windows Installer 3.1 or later
o Internet Explorer 5.01 or later
Page 5
User Guide
Folder Agent
Tutorial
In this tutorial I am going to take you through the steps to setup a simple archiving
application. This application will monitor a folder on your disk and when a file is written to
the folder it will move it to another folder based on the current date.
We start by creating a folder called Input in the root of the C: drive. This will be the
monitored folder.
When you start Folder Agent you will see the main window. This is split with the top half
showing any monitors you have setup and the bottom half is a log of activity in Folder
Agent. If it is the first time you have run then the log have a single message telling you how
many days are left in the trial.
Page 6
User Guide
Folder Agent
Click the Add button in the toolbar to create a monitor.
Now you can choose which type of monitor you need, in this case we will select a Folder
Monitor to watch a local folder.
Folder Agent will ask you to select the folder you want to monitor using the standard
Windows folder browser window. Select the folder C:\Input you created earlier.
You will now see the configuration window where you can tell Folder Agent what actions to
perform when a file is created or changed in the folder.
Page 7
User Guide
Folder Agent
The configuration window is split in two halves; the left panel has a tree view with nodes
for the monitor and each action. The right panel is a property grid that lets you change the
properties for each tree node.
The first node in the tree represents the folder monitor. Underneath it we will add the
actions associated with the folder. There is also a Add node that lets you add actions.
Clicking this add node lets us select an action to add to the Folder Monitor.
Page 8
User Guide
Folder Agent
Select the Move File action and click on the Add button. A new Move File node will appear
under the Folder Monitor.
Each node on the tree has properties associated with it that are displayed in the property
grid in the right panel of the window. Try selecting the two nodes on the tree and you will
see the property grid updates to show the appropriate properties.
We aren't quite finished with the Move File action; we still need to tell it where to move the
file to so make sure you have the Move File node selected on the left then look for the
property Destination Folder in the property grid.
This field supports a simple templating language so it can be created dynamically every
time the action runs. Start by pasting in this path:
C:\Output\{{ Now | dateformat 'yyyy\\MM\\dd'}}
The first part of the path is a root folder C:\Output\, the part starting with {{ and ending
with }} is the template. In this case the template uses the variable Now to obtain the current
date and time then applies a filter to that date to format it.
If this action is run on Christmas day 2012 then the path would be transformed to:
C:\Output\2012\12\25
If these folders don't exist then the Move File action will create them automatically for you.
Your property should look like this:
Page 9
User Guide
Folder Agent
So that is our configuration done, click on the Save button and Folder Agent will start the
monitor.
To test our new configuration open Notepad and enter some text then save a file in the
C:\Input folder. If you look at the Folder Agent log you will see a message saying it has
moved the file. Look in the output folder and you will find new folders created based on the
date with the file in them.
Hopefully this has given you a flavor for how Folder Agent works. The rest of this user
guide will cover each of the topics in more detail.
Page 10
User Guide
Folder Agent
Folder Monitor
The folder monitor is responsible for watching a folder for new or modified files; it then
runs each of its child actions in turn.
When you add a Folder Monitor to your configuration Folder Agent will prompt you to
select a Folder. You can change this by changing the Folder property in the property grid.
Clicking the ellipsis button lets you browse for a folder.
There isn't much to configure for this monitor, just the folder you are monitoring.
The title is just for display purposes, you can change this to something descriptive for your
configuration.
Set the Recursive folder monitor property to true to monitor sub folders inside the
monitored folder.
Stability tells Folder Agent how long to wait for the file to not be touched for. Some
applications write a file by repeatedly opening writing and closing the file. Setting the
Stability property lets you specify a time in milliseconds to wait before processing the file
so you can be sure the application has finished.
You can add as many Folder Monitors to your configuration as you need however you
should not have two or more Folder Monitors watching a single folder.
Files are processed synchronously, this means the actions are run one at a time and the
next modified file isn't processed until the last file has been finished.
Folder Monitors run asynchronously, this means two or more Folder Monitors could be
running their actions at the same time.
Page 11
User Guide
Folder Agent
The Folder property is fixed; it does not accept template parameters. It also does not
support removable media such as CDs, DVDs or USB memory sticks.
Versions 2008-05-18 and later include file patterns for matching and ignoring files. You can
enter a comma separated list of file patterns to match against. For instance to exclude any
.tmp or .bak files enter *.tmp,*.bak in the ignore property.
Page 12
User Guide
Folder Agent
Remote Monitor
The Remote Monitor lets you monitor a folder on a remote site, potentially over the
internet. This monitor uses the SFTP protocol so your remote server needs to be running
this protocol. Folder Agent does not support basic FTP as this is not secure.
There are quite a few properties to configure for the remote monitor, split between the
connection and how files are processed. The remote monitor polls the remote site for new
and changed files which is slightly different to the basic folder monitor.
The interval property tells Folder Agent how long to wait between each check for new files.
It starts a new connection for each check for new or changed files. This can be set in
milliseconds, seconds, minutes or hours.
Download file sets whether the changed or new file should be downloaded before the
actions are run. It is stored in the %temp% folder and cleaned up after the actions have
run. For most applications I would expect this to be true.
Delete remote file tells Folder Agent to delete the file on the remote site after the actions
have run, this is false by default for safety but in most applications I would expect this to be
true as well.
Page 13
User Guide
Folder Agent
File patterns to match and file patterns to ignore are a comma separated list of files to
match or ignore. For instance to exclude any .tmp or .bak files enter *.tmp,*.bak in the
ignore property.
Set the Recursive folder monitor property to true to monitor sub folders inside the
monitored folder.
Stability tells Folder Agent how long to wait for the file to not be touched for. Some
applications write a file by repeatedly opening writing and closing the file. Setting the
Stability property lets you specify a time in milliseconds to wait before processing the file
so you can be sure the application has finished.
The SFTP settings are the authorization settings to connect to the remote server. The
remote server property uses the UNIX convention of forward slashes (/) as a directory
separator.
Default authentication is by username and password, if you want to use public/private key
authentication then set the Authentication property to PrivateKey and set the Private Key
Path property to the private key. The private key should be in OpenSSH format, if you are
using a Putty key then you will need to use puttygen.exe to export an OpenSSH key. If your
key uses a passphrase then you will need to enter this in the Private key pass phrase
property.
Page 14
User Guide
Folder Agent
Copy File
Copy File is an action; it copies a file from the monitored folder to another folder.
The file is copied to the destination folder so this is a required property. If the Destination
File property is blank then the file retains its original name, otherwise it takes the name in
the property.
Both the Destination Folder and Destination File properties can contain templates to
make these paths dynamic.
By default Folder Agent reports an error if you copy onto a file that already exists. Changing
the Overwrite Destination property to true allows you to overwrite existing files.
Page 15
User Guide
Folder Agent
Move File
Move File is an action; it moves a file from one the monitored folder to another folder.
The file is moved to the destination folder so this is a required property. If the Destination
File property is blank then the file retains its original name, otherwise it takes the name in
the property.
Both the Destination Folder and Destination File properties can contain templates to
make these paths dynamic.
By default Folder Agent reports an error if you move onto a file that already exists.
Changing the Overwrite Destination property to true allows you to overwrite existing files.
Page 16
User Guide
Folder Agent
Run Program
The Run Program action executes an external program, script or batch file. This is useful if
you need some extra functionality that doesn't exist in Folder Agent.
The Program property is the path to the executable, script or batch file. Parameters are
the parameters passed to the program. By default the Parameters property is set to:
{{ Path }}
This expands out to the path to the modified or created file.
Note: If your path contains spaces you will probably need to surround it with quote marks,
for example: "{{ path }}"
Timeout is the number of seconds to wait for the program or script to complete. If you set
this to -1 it will wait forever, set it to 0 to not wait at all.
Note: If the action does timeout then Folder Agent will go on to the next action. If the
program you are calling has a lock on the file this may cause the next action to fail.
Setting Minimised to true means the program will run in the taskbar but any windows will
not be visible.
Page 17
User Guide
Folder Agent
Delete File
Delete File deletes the file you specify, normally the changed or written file. Typically you
would add this at the end of your list of actions if you no longer need the original file.
By default the file is sent to the Recycle Bin, if you want to permanently delete the file then
set the Permanently Delete property to true.
Path is the path to the file, by default it is set to:
{{ path }}
This is the path to the original file; change it if you want to delete some other file.
Page 18
User Guide
Folder Agent
Compress
Compress creates a zip file with each child file or folder added to the zip file. You can either
zip a single file, perhaps before your email it or a folder of files. Each single file or folder of
files is added as a child of the Compress action.
You can add as many files or folders to the compress action as you need.
By default Compress will not overwrite an existing file, to change this set the Overwrite
Destination property to true.
The Destination File property is dynamic; you can include template variables in it.
Page 19
User Guide
Folder Agent
Expand
The Expand action extracts the files from a zip archive.
There are two properties, both of which support template text. The Zip file path property
is the path to the source zip file. The Destination folder property is the folder you want to
save the contents of the zip file to.
In the example in this screen shot the Zip file path property is set to {{ path }} to trigger on
new files in our watched folder and the Destination Folder property uses the original file
name. So if you created a file test100.zip then the contents would be saved in the folder
test100\
Page 20
User Guide
Folder Agent
Action List
The Action List is useful if you want to group together a set of actions. Each child of the
action list is run in turn from top to bottom.
There are no properties besides the title of the object.
Page 21
User Guide
Folder Agent
Log Message
Log Message sends a message to the log file and log window. This is useful for diagnostics
and as an aid to setting up Folder Agent.
The Message property supports templates so you can customise the message with
information about the file. Set the Error property to true to log an error.
Page 22
User Guide
Folder Agent
Send Mail
Send Mail lets you send an email message, optionally with attachments. Before you set this
up you need access to a SMTP mail server that allows relaying of email messages. If you
aren't sure what this is your ISP or IT administrator should be able to tell you.
Before adding the Send Mail action you should configure the SMTP server details from the
Tools->Config menu.
The port is typically set to 587 for secure connections, 25 for normal connections.
Page 23
User Guide
Folder Agent
The action itself has details about the message you are sending including who it's from,
who it is going to and the content of the message.
The Body uses \n to delimit new lines although you will probably find it easier to use the
ellipses button to launch the template editor to enter the body.
Both the subject and body can uses templates for dynamic content.
The body is always sent in plain text format.
Attachments are added as child nodes on the tree:
Each attachment has a number of properties that tell it what file to attach, the content type
and the name to use in the email message.
The path and attachment name can both include templates.
Page 24
User Guide
Folder Agent
You can attach a folder of files instead of a single file. Use the include and exclude filters to
choose which files are attached to the email.
Attaching a folder of files introduces a new variable current_path. Use this in combination
with the the getmimetype filter to automatically determine the content type for each file as
it is added to the outgoing message.
Page 25
User Guide
Folder Agent
Options
The Tools -> Options menu lets you configure both the SMTP server settings for sending
email and the start and minimise behaviours.
Start Minimised tells Folder Agent to start with the main window minimised. Minimise to
the notification area hides the icon in the notify tray.
The SMTP options are documented with the Send Mail action.
Page 26
User Guide
Folder Agent
Log Window
When you start Folder Agent the main window you see includes a log window. This shows
a running log of the activity in Folder Agent and should help you diagnose any problems.
Right clicking in the log window pops up a menu that lets you clear the log, copy it to the
clipboard or open the configuration folder.
The configuration folder contains a text file with all the historical log information.
You can backup your configuration by saving the folderagent.xml file.
Page 27
User Guide
Folder Agent
Properties
Each node on the tree has properties associated with it that change its behavior. You can
modify those properties by selecting the node on the tree then selecting each property by
clicking on it.
Many of the properties have a property editor associated with them, this is a window that
pops up when you click the ellipsis button on the right of the property. These windows
are there to make editing the property easier. For instance if you open the property editor
for the Program property in the Run Program action it will launch a window that lets you
browse for a file.
One of the more useful property editors is available on template fields, this has an insert
button and menu that lets you insert template variables and filters.
The Variable and Filter menus are enabled and disabled depending on where the cursor
position is in the template text.
Page 28
User Guide
Folder Agent
Templates and Filters
Templates let you insert some text into a property as the action is running. Using this you
can make up a path based on several variables available to you.
Templates always start with the sequence {{ and end with }}. The first information in the
template is the variable you want to insert and this is followed by any number of vertical
bar characters | and filters.
So a basic template for an email subject might be:
The file {{path}} has just been created or modified
If the path to the file was C:\Input\test.txt then the template would get converted to:
The file C:\Input\test.txt has just been created or modified
There are two variables available in Folder Agent:
Path
Path holds the path to the original file that triggered the actions to run.
Now
Now holds the current date and time.
Sometimes you will want to modify the value a variable holds, this is where filters come in.
You can add as many filters to a template as you want, separating each one with a vertical
bar.
For instance if we want to extract just the file name from a path we can use the filename
filter:
{{ path | filename }}
Here a path to a file like C:\Input\test.txt becomes text.txt
We can extend this with extra filters, perhaps we want to remove leading and trailing
spaces on the file name, then we use a template like:
Page 29
User Guide
Folder Agent
{{ path | filename | trim }}
UTCNow
UTCNow is similar to Now except it uses the UTC time zone.
Temp
{{ temp }} expands to the users temporary folder.
Base_Path
{{ base_path }} points to the monitored folder.
Relative_Path
{{ relative_path }} is the path to the file relative to the monitored folder. This is useful if
you have enabled monitoring of subfolders in your folder monitor. It will allow you to
create sub folders when you move a file.
Imagine you are monitoring a folder C:\Input and in that file there is a sub folder
C:\Input\Data and a new file is created C:\Input\Data\Order.txt. The variable {{
relative_path }} will be set to Data\Order.txt.
Now if you want to move that file to C:\Output\Data\Order.txt then you can set the Folder
property to C:\Output\{{ relative_path | directory }}.
Attributes
If you right click on the column headers in the detail view in Explorer and select More there
are a huge number of attributes available from the model of camera used to take a photo
through to the number of words in a Word document. Not all of them are available for
every file but if you can see them in Explorer then you can use them in a template in Folder
Agent.
They are accessed using the attributes variable followed by a period then the attribute
name. So to use the camera mode you might use the template {{ attributes.cameramodel
}}.
The available attributes do depend on which edition of Windows you are running, the
easiest way to select one is to edit your text in the template editor and use the Insert>Variable->File attributes menu.
Page 30
User Guide
Folder Agent
Filters
The filters available are:
trim
Remove any leading and trailing whitespace characters.
lower
Convert the string to lower case.
upper
Convert the string to upper case
filename
Extract just the file name from a path.
filenamewithoutextension
Extract the file name without extension from a path.
extension
Extract just the file extension from a path.
directory
Extract the directory from a path.
getmimetype
Determine the mime type of a file. This filter attempts to determine the mime type from the
file %appdata%\Folder Agent\mimetypes.txt. If it can’t find an entry then it defaults to
application/octet-stream
md5
Calculate the MD5 hash of a file.
{{ path | md5 }}
Page 31
User Guide
Folder Agent
sha256
Calculate the SHA256 hash of a file.
{{ path | sha256 }}
dateformat
Format the date according to a format string. An example of this is:
{{ Now | dateformat 'yyyy\\MM\\dd'}}
The \\ in the format string is an escape; it inserts a single \ character. yyyy gets converted
to the year, MM to the month and dd to the day. Google ".net date format" for the full range
of format strings available (there are a lot!)
Note: Variables have a type so there are some combinations that won't make sense, for
instance adding the dateformat filter to the Path variable will cause an error.
Page 32
