Home | Appendix

Quick links: |  | Smart Rules Batch Processing Exporting and Importing

|  |  | Smart Rules and Batch Processing

Not everyone is a coder, perhaps even you. But that doesn't mean you don't have automation needs. DEVONthink has two related technologies that allow you to process your data by constructing a chain of predefined commands: smart rules and batch processing. While the former are for more transparent background processes and the latter for handling selected items, both share common traits and methods. Understanding one leads to understanding the other. Smart Rules Smart rules are smart groups‚ evolved. Built in the same style as smart groups, smart rules don't just show items matching criteria, they can act on them! From something as simple as adding (or changing) a color label, to modifying a filename then filing a document in another location, smart rules provide some powerful automation possibilities. And they're not just for the technically inclined. No programming experience is needed for almost every action available. Smart rules are conceptually simple and can be summed up as follows: When this event occurs > do this action > on items matched > in this location. Smart rules are made of four parts: A location: This is where the smart rule will look for matching items. Matching criteria: Like a smart group, you can specify criteria to be matched. The smart rule will only act on the matched items. An action: This is the action the smart rule performs when the event occurs. An event: This is an event that causes an action to occur, e.g., an "On Quit" event. If used in a smart rule, a specified action would run when you quit DEVONthink. Create a smart rule: Smart rules can be created in one of two ways: Click the + button at the bottom of the sidebar and choose New Smart Rule. The Search in dropdown will target the current location. Control-click an item in the sidebar and choose New Smart Rule from the context menu. This will specifically target that item in the Search in dropdown. Note in either case you can change the Search in parameter to target other locations, including all open databases.
Note: Smart rules are considered global objects and can be created only in the Navigate sidebar of a main window. If you want to create a smart rule for a group in the item list, choose Data > Reveal to display it in the Navigate sidebar.
When you create a new smart rule, you will be shown the predicate editor, just as you see with smart groups. Just follow these simple steps to define the parameters of the rule (with an example): Name: Give the rule a name, like Label Edited Screencaptures. Location: Set the Search in dropdown to target your desired location, like a group you add screen captures to. The more specific the better; a good idea is to use e.g., a database's inbox. Matching: Add any criteria to be matched, e.g., `Name begins with screen` and `Kind is Image`. Event: Choose an event to trigger the smart rule, like specifying `On Save` to run the smart rule when matched items are saved in DEVONthink Action: Choose an action for the smart rule, perhaps `Change Name` to add "_edited" to the name. This rule shown above would add "_edited" as a suffix to the name of any edited images whose name begins with "screen". One step further‚ chained actions: If you hadn't noticed, there's a + button to the right of the action you specified. And yes, that means you can chain multiple actions in a smart rule! For example, we could add an action to open the edited imaged in the system default application after it has been renamed. Understanding the input: In a smart rule, there always is only one input. You can't use conditionals or split the actions into a parallel process. A matched document is passed along through the entire process. So if you have a smart rule processing Markdown files and one of your actions is `Convert to Rich Text`, the resulting rich text file is created but not passed on to the next actions. The originally matched Markdown is still the input. However, there are two actions that allow switching the input: `Duplicate & Continue` and `Convert & Continue`. The items created by these actions become the input for the following actions. In our example, these actions would pass on the resulting rich text document as the input for the rest of the rule. Order of operations: If you have more than one smart rule targeting the same location and/or types of files, they will run in the order they appear in the Navigate sidebar. The topmost rule will execute first, then the second, and so on. Be aware one rule could make a change that affects whether an item is matched by subsequent rules. If it does, those rules logically will not process the items. Drag related smart rules into the order they should run or stop and reconsider how your rules are set up. Chaining smart rules: Creating smart rules with more limited functions is often useful. For example, a rule that just files documents based on a certain custom attribute can be used on selected documents or by drag and drop to the rule. Now say you have another rule with more complex functions, e.g., moving a document into a database, doing OCR, then adding custom metadata. Provided it's using the same custom metadata, instead of adding the same actions as the previous rule, add the Apply Rule action and choose the filing smart rule. Now add another smart rule that should also file things based on the same custom metadata but in a different location. Use the `Apply Rule` action there as well. Now both rules can use the filing smart rule's actions without having to redundantly add their own actions. This is a powerful way to extend the functions of a smart rule while also using the simpler functions, when needed. Working Safely: In smart rules, the actions are executed based on the event handler you're using. For testing, set the event trigger to `On Demand`. This way you can select the rule to see its matches, then Control-click it and choose `Apply Rule` to run it and see the effects on the matched items. Once things are working as expected, you can add other event triggers to suit the situation. Also be aware the effects of smart rules are very broad, i.e., they affect all the items they match. While you are testing, it's a good idea to put some limiting criterion in place. For example, instead of matching all images in all databases, try matching images in a specific group or only images that begin with "Screen". Batch Processing Smart rules are useful for repetitious actions, usually happening in the background. For times when you need to make impromptu changes on specific items, e.g., prefixing a date to the name of several documents, batch processing is the best option. Select a few documents to process, then choose Tools > Batch Process. The Batch Processing window appears where you can create your chain of actions, just as described for smart rules. Then press OK and the documents are modified. And if this is something you'll do often, you can create new reusable configurations as you need them. Note not every smart action is available in batch processing. However, for most actions the available ones are more than sufficient. Exporting and Importing If you want to share or backup individual smart items, it is easily done. The simplest way to export a smart item is to drag and drop it to the Finder. Smart rules export as `.dtSmartRule`, batch configurations as `.dtBatchProcess` files. You can also choose Export from the context menu for a smart rule or batch configuration. And lastly, you can export from the action menu in the Batch Process window. To import these items, you can simply double-click the exported file to reinstall it. Alternately, for smart rules, you can also drag and drop directly into the Smart Rules or choose Import from the context menu. For batch configurations, you can drag and drop to the Configurations section of the Batch Process window or choose Import from the context menu or action menu. If you want to share or independently backup all these smart items, you can find the `BatchProcessing.plist` and `SmartRules.plist` in the `~/Library/Application Support/DEVONthink` directory. For your reference, there is a complete list of available Events and Actions. For those interested in the using script-based actions, continue to the next section…