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 [email protected] 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
