Guides and Sample Code

Developer

Mac Automation Scripting Guide

On This Page

Watching Folders

The ability to watch folders and take action on incoming items is a powerful automation technique that enables the creation of fully unattended workflows. A watched folder might be used, for example, to watermark incoming photos, convert them to PDF, and email them to clients for review. Many companies set up script servers—dedicated robot machines that watch folders and process detected items, allowing employees to offload tedious and repetitious work in order to focus on other important tasks.

In OS X, there are two primary ways to set up scripting-based watched folders: folder actions and stay open script apps.

Using Folder Actions to Watch Folders

Folder actions is a feature in OS X that lets you connect scripts to folders on your Mac. A folder action script includes one or more event handlers that run in response to certain events, such as opening, closing, or adding items to the connected folder. With folder actions, you can create automated workflows that:

  • Notify you when new files and folders arrive in a folder

  • Notify you when existing files and folders are removed from a folder

  • Perform processing of newly detected files and folders

  • Initiate any automated task when a new file or folder is detected

  • Adjust or reset the view properties of a folder’s window when it’s opened, closed, or resized

Write a Folder Action Script

The event handlers supported by folder actions are defined in the Standard Additions scripting addition that comes with OS X. They are:

Folder event

Event handler

Parameters

Items—files or folders—are added to the folder

adding folder items to

  • Direct parameter—The connected folder.

  • after receiving—A list of items added to the folder.

Items are removed from the folder

removing folder items from

  • Direct parameter—The connected folder.

  • after losing—A list of items removed from the folder. For items that were deleted, names of the removed items are provided.

The folder is opened in a new Finder window

opening folder

  • Direct parameter—The connected folder.

The window of a folder is closed

closing folder window for

  • Direct parameter—The connected folder.

The window of a folder is moved

moving folder window for

  • Direct parameter—The connected folder.

  • from—The coordinates of the folder’s window before it was moved.

To create a folder action script
  1. Create a Script Editor document.

  2. Add one or more folder action event handlers to the document.

  3. Save the document as a compiled script to one of the following folders:

    • /Library/Scripts/Folder Action Scripts/—The script can be used by any user.

    • ~/Library/Scripts/Folder Action Scripts/—The script can be used by the current user only.

The following examples demonstrate how to use different folder action event handlers.

APPLESCRIPT

Open in Script Editor

Listing 18-1AppleScript: Example of the opening folder event handler
  1. on opening folder theAttachedFolder
  2. -- Get the name of the attached folder
  3. tell application "Finder"
  4. set theName to name of theAttachedFolder
  5. -- Display an alert indicating that the folder was opened
  6. activate
  7. display alert "Attention!" message "The folder " & (quoted form of theName) & " was opened."
  8. end tell
  9. end opening folder

APPLESCRIPT

Open in Script Editor

Listing 18-2AppleScript: Example of the closing folder window for event handler
  1. on closing folder window for theAttachedFolder
  2. -- Get the name of the attached folder
  3. tell application "Finder"
  4. set theName to name of theAttachedFolder
  5. -- Display an alert indicating that the folder was closed
  6. activate
  7. display alert "Attention!" message "The folder " & (quoted form of theName) & " was closed."
  8. end tell
  9. end closing folder window for

APPLESCRIPT

Open in Script Editor

Listing 18-3AppleScript: Example of the adding folder items to event handler
  1. on adding folder items to theAttachedFolder after receiving theNewItems
  2. -- Get the name of the attached folder
  3. tell application "Finder"
  4. set theName to name of theAttachedFolder
  5. -- Count the new items
  6. set theCount to length of theNewItems
  7. -- Display an alert indicating that the new items were received
  8. activate
  9. display alert "Attention!" message (theCount & " new items were detected in folder " & (quoted form of theName) & "." as string)
  10. -- Loop through the newly detected items
  11. repeat with anItem in theNewItems
  12. -- Process the current item
  13. -- Move the current item to another folder so it's not processed again in the future
  14. end repeat
  15. end tell
  16. end adding folder items to

APPLESCRIPT

Open in Script Editor

Listing 18-4AppleScript: Example of the removing folder items from event handler
  1. on removing folder items from theAttachedFolder after losing theRemovedItems
  2. -- Get the name of the attached folder
  3. tell application "Finder"
  4. set theName to name of theAttachedFolder
  5. -- Count the removed items
  6. set theCount to length of theRemovedItems
  7. -- Display an alert indicating that items were removed
  8. activate
  9. display alert "Attention!" message (theCount & " items were removed from folder " & (quoted form of theName) & "." as string)
  10. -- Loop through the removed items, performing any additional tasks
  11. repeat with anItem in theRemovedItems
  12. -- Process the current item
  13. end repeat
  14. end tell
  15. end removing folder items from

Attaching a Folder Action Script to a Folder

A folder action script must be connected to a folder in order to use it. This is done with Folder Actions Setup, an app that’s launched from the Finder’s contextual menu.

To attach a folder action script to a folder
  1. Control-click the folder in Finder.

  2. Choose Folder Actions Setup from the contextual menu.

    The Folder Actions Setup app launches, the folder is automatically added to the Folders with Actions list, and you’re prompted to select a script.

  3. Choose a script to connect to the folder and click Attach.

    image: ../Art/folderactionssetup_attachfolder_panel_2x.png
  4. Make sure the Enable Folder Actions checkbox is selected, as well as the On checkboxes next to the folder.

    image: ../Art/folderactionssetup_main_window_2x.png

Once the script and folder are connected, the folder action event handlers in the script should run when the corresponding actions occur.

Watching Folders Using an Idle Loop and a Stay Open Script App

Although folder actions provide efficient folder watching capabilities, some scripters prefer to implement customized folder watching workflows that provide more control over the folder watching process. This is typically done by creating a stay-open script with an idle handler that checks a folder at regular intervals for new items to process. Listing 18-5 demonstrates an idle handler-based script that watches an Input folder on the Desktop.

APPLESCRIPT

Open in Script Editor

Listing 18-5AppleScript: Watch a folder for files using an idle loop
  1. on idle
  2. -- Locate the folder to watch
  3. set theFolder to locateAndCreateFolder(path to desktop folder, "Input")
  4. -- Watch the folder
  5. watchFolder(theFolder)
  6. -- Delay 2 minutes before checking the folder again
  7. return 120
  8. end idle
  9. on watchFolder(theFolder)
  10. -- Check for files in the folder
  11. tell application "Finder"
  12. set theFilesToProcess to every file of theFolder
  13. end tell
  14. -- Stop if there are no files to process
  15. if theFilesToProcess = {} then return
  16. -- Locate an output folder
  17. set theOutputFolder to locateAndCreateFolder(path to desktop folder, "Output")
  18. repeat with aFile in theFilesToProcess
  19. -- Process the current file
  20. -- Move the current file to the output folder so it doesn't get processed again
  21. tell application "Finder"
  22. move aFile to theOutputFolder
  23. end tell
  24. end repeat
  25. end watchFolder
  26. -- Locate a folder, creating it if it doesn't exist
  27. on locateAndCreateFolder(theParentFolder, theFolderName)
  28. tell application "Finder"
  29. if ((folder theFolderName of theParentFolder) exists) = false then make new folder at theParentFolder with properties {name:theFolderName}
  30. return (folder theFolderName of theParentFolder) as alias
  31. end tell
  32. end locateAndCreateFolder

Folder Watching Best Practices

Regardless of what method you use for folder watching, follow these best practices to produce an efficient and reliable workflow:

  • Wait for items to finish writing to disk before processing them.

  • Move processed items to an output folder so the same items aren’t detected and processed a second time.

  • Handle errors gracefully, such as by moving problematic items to an error folder so other processing can proceed.

  • Bring dialogs and alerts to the front so they’re visible and can be addressed.