Appendix : Smart Rule Events and Actions

Smart Rule Events and Actions

Smart rules in DEVONthink provide many powerful actions and events that can trigger these actions. Below is a list of the available options for both.

Events

When an action is triggered is almost as important as the action itself. Actions can be triggered when any of these events occur:

On Demand: Run only when Apply Rule is selected in a contextual menu or Tools > Apply Rules.
On Startup: Runs when DEVONthink launches.
Before Synchronization: Runs all actions before DEVONthink begins synchronizing to any sync location.
After Synchronization: Runs all actions after DEVONthink completes synchronizing to any sync location, i.e. all uploads, downloads, and changes are committed.
On Quit: Runs when DEVONthink quits.

Every Minute: Runs the specified actions every minute.
Hourly/Daily/Weekly: Runs the specified actions on an hourly, daily, or weekly schedule.
On Workdays: Runs on Monday through Fridays.
On Weekends: Runs on Saturday or Sunday.

On Creation: Runs when a new document is created in the specified location. To trigger actions when taking notes or screen captures with the Sorter, choose Via Sorter.
Before Saving: Runs before saving a matched document.
After Saving: Runs after saving a matched document.
On Imprinting: Runs when any matched document has been imprinted.

On Import: Runs when documents are added to the specified location.
On Clipping: Runs when documents are added via clipping, e.g., via menu commands, the Sorter, DEVONagent, bookmarklets, or AppleScript.
On Download: Runs when items are downloaded via DEVONthink's Download Manager.
On Scan: Runs after a scanning operation has completed.
On OCR: Runs after an OCR operation has completed.
On News: Runs when an RSS feed refreshes and receives new articles.

SERVER

On Upload: Runs when an item is uploaded through DEVONthink's web server.

On Open: Runs when a matching item is opened in a new document window or viewed in a main window.
On Open Externally: Runs when a matching file is opened in an external application.
On Launch URL: Runs when the URL associated with the item is launched.
On Reminder: Runs when an alarm set on a matching item's Reminder comes due.

On Renaming: Runs after matched items are manually renamed.
On Moving: Runs when matched items are moved to the specified location.
On Classifying: Runs when matching items are classified by DEVONthink.
On Tagging: Runs when matched items are tagged
On Labelling: Runs when a label is added to or changed on an item.
On Replicating: Runs when matched items are replicated.
On Duplicating: Runs when matched items are duplicated.
On Moving into Database: Runs when indexed items are moved into the database, becoming imported items.
On Moving to External Folder: Runs when imported or created items in a database are moved to external locations, becoming indexed items.

You can and and remove multiple event triggers by pressing the + or - buttons. Fox example, you could use an On Import and an On Moving event trigger to act on files imported or moved into it.

Actions

The power in smart rules is the actions. DEVONthink provides actions that cover simple tasks, e.g., prefixing a filename, all the way to ultra-powerful AppleScript injection via external or embedded scripts. Since you can chain multiple actions together, the possibilities are nearly endless. Here's a list of available actions:

Bounce Dock Icon: Causes DEVONthink's dock icon to bounce. This will only trigger when DEVONthink isn't the active application.
Display Notification: Shows a message via the Mac's Notification Center. Notifications need to be enabled in System Preferences > Notifications for Display Notification to operate correctly.
Display Alert: Shows a message in an alert window.
Speak Text: Using your computer's voice synthesis, it will speak the message you specify.
Play Sound: Plays a selected system alert sound.

Send Mail: Enter email addresses to send the matching items. This can be a comma-delimited list of addresses, names, or enter the name of a group you've defined in your contacts.
Add to Reading List: Add the matched items to the Reading List.

Open: Opens in a document window, a file that triggered or was produced by a smart rule.
Open Externally: Open the matched file in the system default application.
Launch URL: Open the URL associated shown in the Info Inspector & URL.
Check Bookmarks: Checks the URL of the matched items. Any issues with the URL are reported in the Log window or the Log popover.
Apply Rule: Perform the actions of another smart rule on items passed by the current smart rule. The items passed by the initial smart rule must match the criteria of the second smart rule to trigger it. This can be useful after performing smart rule actions like OCR or executing scripts, helping to avoid redundant or scheduled smart rules.
Execute Script: Execute External or AppleScript/JavaScript scripts in the embedded script editor popup. Embedded scripts are only available to the smart rule they are created in. Read more...

Item scanning: The next two actions allow you to scan the name or text of a document and use the results when found. Each of the actions also has a parameter you specify for the type of data you're scanning for. These actions and parameters can be used with subsequent actions that support placeholders, e.g., Scan Text: Date → Document Date with Change Modification Date. If the action returns no results, actions using the results will not be executed. However, unrelated actions in the smart rule chain will be executed normally.

Scan Name: Scans the name of the file.
Scan Text: Scans the contents of the file.

The following four parameters are used with the Scan Name and Scan Text actions. With String, Date, and Amount, a prefix and/or suffix before/after the wildcard has to be specified.

String: An asterisk (*) wildcard specifies data to be captured. Other terms added will be used to help located the desired string. In subsequent actions, use the Document String placeholder to represent the captured string.
Date: Similar to String parameter, use the desired format of the Document Date placeholder to represent the captured string in subsequent actions.
Amount: Similar to String parameter, use the desired format of the Document Amount placeholder to represent the captured string in subsequent actions.
Regular Expression: Items in parentheses are captured; items outside parentheses are ignored. You can specify multiple captures in an expression. Using the captured text in subsequent actions is specified by using backslash, \, and the number of the capture, starting at 1. Note we use Apple's NSRegularExpression which supports the ICU regular expression syntax.

Example:

Using the String parameter, Invoice * would capture 0012345 in a file named Invoice 0012345..
Using the Date parameter, * would capture the date in a file named 2020-01-01.
Using the Amount parameter, $* would capture the dollar amount detected.
Using the Regular Expression parameter, Bill To: ([A-Za-z0-9 ,]+) would capture the name of the person or company billed. \1 would be used in the subsequent action.

Change Name/Aliases/Comment/Label/Rating: Change the specific attribute of the matched file. For items with an existing attribute, e.g., a comment, a placeholder will preserve the existing value.
Mark: Toggle the state of read/unread, flagged/unflagged, and locked/unlocked. Note you change more than one of these attributes with one action, but you can chain more than one Mark action in the smart rule.
Change Creation/Modification Date: Change the creation or modification date of matched files to: current, addition, creation, modification, or the document date.

Add Tags: Add tags to the matched files. As you type, tags from all open databases will be suggested. Press the comma key to commit the tag.
Add Tags from Document: Adds existing tags if they are detected in the matched document's contents.
Remove Tags: Removes specific tags you enter.
Remove All Tags: Removes all tags from the items.
Tags: Adds or converts tags to matched documents from these commands: Convert HashTags, Convert Keywords, Convert Properties, Convert Geolocation, Add Tags to Images, and Scan Barcodes. (See the View menu for more information on these options.)

Move/Replicate/Duplicate: Move, replicate, or duplicate a matched file to a chosen location.
Duplicate & Continue: Duplicates matched files and applies subsequent actions to the copies.

File: Allows you to file items into a group. Specify subgroups using a forward slash, e.g., 2019/DEVONtech would create or file into the DEVONtech subgroup of a 2019 group in the current group. You can use placeholders to define the location.
Classify: Using our AI, this will attempt to move any matched files to an apropos location. Failures to classify files are noted in the Log window.

Move Into Database: Moves indexed items into the database, essentially importing them. Note this removes the file from the original location in the filesystem.
Move To External Folder: For an item located in an indexed group, this moves the file to the indexed folder in the Finder.

Convert: Attempts to convert files into plain/rich text, formatted notes, Markdown, HTML, web archive, or PDF.
Convert & Continue: Converts files and applies subsequent actions to the copies.
Thumbnails: Adds, updates, or removes a matched file's thumbnail.

PRO

OCR: This will perform OCR on a file, if possible. Choose a format to generate a new file in the selected file type. Note the file type selected will override the option set in Preferences > OCR > Convert incoming scans to. Choose Apply to convert a matched file directly to a PDF with OCR. This action does not generate new files.
Imprint: Apply the selected imprint to any matching files, if possible.
Custom Metadata: If you have specified custom metadata fields, you will have options to change values with an action. For example, if you had a Boolean field named "Done", you could have the action set this field to true when the action is triggered.

Move to Trash: Move the item to the database's trash. The items are not removed from the database until the trash is emptied.
Delete: Be very cautious with this option. Delete truly deletes a file. It is not sent to the database's trash. It is not sent to the Finder's trash. It is completely deleted.