Appendix : Smart Rule Events and Actions

Smart Rule Events and Actions

DEVONthink provides many powerful actions for use with smart rules and batch processing. Smart rules run when certain events happen, e.g., when you open a file or DEVONthink syncs. These are called event triggers and are listed first. Following that are the available actions for both functions.

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 context 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.
Via Sorter: Runs when creating various note types via the 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 Edit Externally: Runs after a document is edited in an external application and saved.
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 Commenting: Runs after modifying Finder Comments on an item, including changes made to indexed items in the Finder.
On Labelling: Runs when a label is added to or changed on an item.
On Flagging: Runs when an item is flagged.
On Rating: Runs when the Ratings on an item are modified.
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 Replicating: Runs when matched items are replicated.
On Duplicating: Runs when matched items are duplicated.
On Convert: Runs when an item is converted to a new format.
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.
Before Trashing: Runs before a database's Trash is emptied.

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 and batch processing is found in 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.

Note batch processing supports a smaller number of actions than smart rules. Here's a list of available actions with those also usable in batch processing marked with (BP):

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 Settings > 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 a file that triggered or was produced by a smart rule in a document window.
Open Externally: Opens the matched file in the system default application.
Launch URL: Opens the URL shown in the Generic Info inspector for a matched item.
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.
Stop evaluating rules: Stops the rule from proceeding to subsequent actions. Most often used while developing and debugging a smart rule.
Apply Script: Run a script on the matched or selected items. Choose a script from installed External scripts. Or choose AppleScript/JavaScript and write your code in the embedded script editor popup. Embedded scripts are only available to the smart rule they are created in. Read more... (BP)
Check Bookmarks: Checks the URL of the matched items. Any issues are reported in the Log window or the Log popover.

Item scanning: Supported both in smart rules and batch processing, 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. (BP)
Scan Text: Scans the contents of the file. (BP)
Find & Replace: Scans one of several attributes or custom metadata fields for specified text and replaces it with another value you provide. You can scan a matched item's: Name, URL, Aliases, and Finder Comments as well as custom metadata with a Single/Multi-line Text or an Identifier data type. Supports case-sensitivity. (BP)

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.

Chat and Scripting: These commands are used for adding script actions processes or integrating an AI model, e.g., ChatGPT, into your automations.

Set Script Input: Choose a property, e.g., the aliases of a file or a chat response, and create a variable for use in a smart rule script. (BP)
Script with Input/Output: Receives the value of a Set Script Input variable and uses it in the script. Outputs a return command to a Script Output placeholder, if passing the results on to subsequent actions. Either action is optional. (BP)

PRO

Chat - Query: Receive an response from a specified AI model to your prompt. Optionally, include a document related to the query. (BP)
Chat - Continue if…: A special conditional action that controls whether subsequent actions should be executed based on a "yes" or "no" response to an AI query. (BP)

Batch Processing Only: There is one action found only in batch processing: User Input. As batch processing is a more impromptu mechanism, it's a good place to initiate user interaction. This smart action opens a dialog for you to enter information, e.g., to be used with the User Input placeholder.

Change Name/Aliases/Comment/URL/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. (BP)
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. (BP)
Change Creation/Modification Date: Change the creation or modification date of matched files to: current, addition, creation, modification, or the document date. (BP)

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

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. (BP)
Classify: Using DEVONthink's internal AI, you can classify matched items to the Same Database or Any Database. Pro / Server users can also use AI to determine a filing location via the Via Chat option.

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.
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.

PRO

Recognize: Processes a compatible media file based on your choices in the AI > Transcription settings.
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 Settings > 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.
Import Email Attachments: Import attachments from matching emails.
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. (BP)