Automate DEVONthink
DEVONthink offers plenty of power and utility when used manually—dragging stuff in; finding, organizing, and editing things; and sharing or exporting things. But you can also put DEVONthink to work for you by configuring it to automate repetitive or time-consuming tasks. Although older versions of DEVONthink supported AppleScript, DEVONthink 3 also includes several other types of automation.
In this chapter, I cover four main ways to automate DEVONthink: using smart rules, reminders, AppleScript, and smart templates.
Work with Smart Rules
As you’ll recall (refer back to Use Smart Groups), a smart group is basically a saved search that lists items matching one or more criteria you specify. A smart rule builds on that concept—instead of merely listing items that meet your criteria, it does something when items meet your criteria. In this way, it’s much like the rules (or filters) your email app offers—for example, when a message comes in with a certain sender, a rule might file it into a particular mailbox; or if a message has a specific subject, your email app might send an autoreply.
But DEVONthink’s smart rules can do fancier things—for example:
When DEVONthink opens, convert any web archives in your inbox that mention your name into PDFs
Every time you move a document with a certain label, change its modification date
Once a week, move any unread items in your global Inbox to the Trash
Perform OCR on every PDF document as it’s imported (not necessary for incoming scans; see Configure OCR Preferences)
Replicate items with a certain tag to a predefined group whenever you open them
Set Up a Smart Rule
What you’ll notice about the example smart rules above is that they all feature search criteria (which can include a specific location, or not, and zero or more attributes), an action (what DEVONthink does with them), and a trigger (what event happens that causes the action to occur, such as opening the app or moving a document). DEVONthink offers a long list of actions to choose from, and a smart rule can also perform a sequence of actions. Similarly, many different events can trigger a smart rule, or you can trigger the rule manually in multiple ways.
To create a smart rule, follow these steps:
Either choose New Smart Rule from the New
pop-up menu at the bottom of the sidebar or right-click (or Control-click) an item in the sidebar and choose New Smart Rule from the contextual menu. The Smart Rule dialog (Figure 79) appears.
Figure 79: Create a smart rule using this dialog. Type in a name for your smart rule.
Specify the scope of the rule: from the “Search in” pop-up menu, choose an inbox, database, group, or tag; or choose Databases to search everywhere.
Fill in the options and search criteria just as you would when creating a smart group (refer back to Use Smart Groups).
So far, what you’ve done is identical to what you would do when creating a smart group. But now, instead of displaying a list of matches, you specify what DEVONthink should do with matches, and when.
From the “Perform the following actions” pop-up menu, choose a trigger—that is to say, an event that must occur in order to make your rule run. There are 38 options, including On Startup, Hourly, On Creation, On Open, On Replicating, On Tagging, and On Moving into Database. Most of these should be self-explanatory, but consult the DEVONthink documentation for details if need be.
If you want your smart rule to run only when you ask it to—for example, by choosing a menu command or dropping a document onto your smart rule—choose On Demand (the default choice).
A given smart rule can be triggered by more than one action. For example, you might have a rule that operates when a document is opened as well as when tags are added. To add another trigger, click the plus
button next to the “Perform the following actions” pop-up menu.From the unlabeled pop-up menu in the bottom portion of the dialog, choose an action that will occur when the rule is triggered and the conditions are met. There are dozens of options, such as Display Alert, Add to Reading List, Change Name, Add Tags, Move, Classify, and OCR. Again, see the documentation for details about any actions that seem unclear.
Some actions require additional information. For example, if you specify Display Alert, you must fill in the text of the alert; if you specify Move, you must fill in a destination.
To make the rule perform an additional action, click the plus
button and fill in the details; repeat as desired.Click OK.
DEVONthink saves the smart rule, which thereafter appears in the Smart Rules section of the Navigate sidebar. (Smart rules are always considered global items, even when they apply only within specific databases.)
From now on, whenever the trigger(s) you chose occur(s), DEVONthink runs the smart rule—it looks in the location you specified for items that match the criteria you set, and if it finds any, it performs the action(s) you requested.
To edit a smart rule later, double-click it in the sidebar; to keep the original and edit a copy, first right-click (or Control-click) the rule and choose Duplicate from the contextual menu. (You might also try this with the smart rules DEVONthink includes by default—such as Filter Duplicates and Automatic Locking—to see how they work.)
Run Smart Rules Manually
If you chose On Demand as a trigger in step 5 above, you can run your rule manually in one of the following ways:
Drag one or more items onto the smart rule icon in the sidebar.
To apply a smart rule only to selected items (assuming they match the rule’s conditions), select one or more items and choose Tools > Apply Rules > Rule Name.
To perform a smart rule on any item in your database that might match it—regardless of what you may have chose when you created it—choose Tools > Perform Rules > Rule Name; read and consider the warning asking if that’s really what you want to do, and click OK if you still want to run the rule.
Use Text Searches in a Smart Rule
DEVONthink’s smart rules (and batch processes) include Scan Name and Scan Text actions. These actions enable DEVONthink to search either the name of a document or its contents for a pattern, which can then be used in a subsequent action. The patterns you search for can include wildcards and regular expressions.
As an example of how you might use one of these actions, see Figure 80, below. In this smart rule, imported documents whose names begin with “TPS Report” are searched for a line that matches the pattern “Report Title: something” (followed by a return), using the regular expression Report Title: (.*)
. The next action then uses that something (1) to rename the document.
If you’re using a String search (instead of a regular expression, as in this figure), the wildcard * (any string) can’t appear alone; it requires a prefix and/or a suffix, such as Date: *. You can then reference that string in another action by typing %Document String% or by right-clicking or Control-clicking in another action’s field and choosing * Document String from the Placeholder submenu of the contextual menu.
Use Reminders
Reminders are yet another feature added in DEVONthink 3. If you’ve ever set an alarm in Apple’s Calendar or Reminders apps to alert you when an event is about to occur, DEVONthink’s reminders will look quite familiar. Any item can have a one-time or recurring reminder. For example, if you’ve imported a webpage but you want to remember to revisit it to check for changes on a certain date, or if you want to set alarms for deadlines relating to a project you’re developing in DEVONthink, reminders can help you with those tasks.
I think of reminders as an automation feature partially because they make things happen at a fixed time or on a recurring schedule without manual intervention, and partly because one form a reminder alarm can take is running an AppleScript (which, as you’ll see later in this chapter, can do just about anything).
To set a reminder:
Select any document or group.
Choose Tools > Inspectors > Annotations & Reminders (Control-3) or click the Annotations & Reminders
icon at the top of the inspector (Figure 81).
Figure 81: The Annotations & Reminders inspector as it appears with a weekly reminder set. From the Remind pop-up menu at the top, choose when the reminder should occur—Never (the default), Once (including preset options of Today, Tomorrow, In Two Days, In One Week, and In Two Weeks), Hourly, Daily, Weekly, Monthly, or Yearly.
For anything other than Never, fill in the details of the day(s), date(s), and time(s) for the reminder, just as in the Calendar app.
From the Alarm pop-up menu, choose the type of alert. In most cases, something visible (Display Notification or Display Alert) or audible (Speak Text or Play Sound) is probably what you want, but you can also send an email, open a document, or run an AppleScript. As with smart rules, the script can be either external (that is, one that’s stored in the designated Reminders folder—see Included Scripts, ahead) or embedded (something you type or paste into DEVONthink). Be aware, however, that if you use an embedded script with a one-time reminder, the script will disappear from DEVONthink once the reminder occurs.
Use AppleScript with DEVONthink
Despite DEVONthink’s incredibly long list of features, it may not do everything you want it to do. Fortunately, it also includes extensive support for AppleScript, which means you can add new capabilities to the app, automate complex sequences of tasks, and integrate DEVONthink in novel ways with other apps running on your Mac.
Many books have been written about AppleScript, and I couldn’t begin to offer a proper guide to using it here. (I can, however, put in a quick plug for my book Take Control of Automating Your Mac!) Instead, what I provide here is simply a quick overview of DEVONthink’s AppleScript support, a few examples of included scripts, and pointers on where to learn more.
AppleScript is an English-like scripting language that was designed to be reasonably easy for non-programmers to learn. (Whether that turned out to be true or not is open to debate!) Apple provides a tool called Script Editor (in /Applications/Utilities) that facilitates writing, running, and debugging scripts (although other, more advanced scripting environments also exist).
An app that can be controlled by AppleScript is said to be scriptable, and DEVONthink is scriptable in the extreme, exposing 90 verbs (commands) and more than a dozen nouns (objects that can be acted on), each with various properties (parameters).
However, you needn’t know any AppleScript to start using these capabilities. DEVONthink includes over 100 preinstalled AppleScripts, which can perform an astonishing range of useful activities as they stand—and can also be used as models when creating your own scripts. These scripts can be used without any special knowledge, in most cases simply by choosing them from a menu—so it’s like having 100 extra features to play with!
I encourage you to try them out, and then if you’re interested, open a few of them in AppleScript Editor to see how they work.
Included Scripts
DEVONthink’s preinstalled scripts fall into several broad categories:
Menu scripts: These scripts appear on DEVONthink’s Script
menu only when DEVONthink is running, and thus are intended to be used from within DEVONthink. This is the largest category, with over 70 scripts. The script files themselves are stored in ~/Library/ApplicationScripts/com.devon-technologies.think3/Menu(and its subfolders); if you add your own script to that folder (or even to a subfolder you create yourself), they’ll appear on the menu too. A few noteworthy examples:Images: Among the scripts on this submenu are ones that can rotate or flip an image, or scale it to various sizes—handy since DEVONthink itself can’t resize graphics, only zoom in or out when viewing them.
Reminders: These scripts create an event or to do in Calendar (or various third-party programs, such as OmniFocus and Things) based on the selected item in DEVONthink—including a link to the item.
Sheets: Although I said earlier that DEVONthink’s sheets can’t do calculations, as spreadsheets can, these scripts add a couple of rudimentary spreadsheet features, such as summing and averaging rows or columns.
Smart rules scripts: A smart rule, discussed earlier in this chapter (see Work with Smart Rules) can trigger an AppleScript to run when the rule’s criteria are met. DEVONthink includes a number of prewritten scripts for smart rules, stored in
~/Library/ApplicationScripts/com.devon-technologies.think3/Smart Rules; again, you can add your own scripts to this folder.Reminders scripts: These scripts are available as actions that run when a reminder’s alarm is triggered (refer back to Use Reminders). Only one example is included: Open Document (which, as the name suggests, opens a specified document when the alarm goes off). These scripts are stored in
~/Library/ApplicationScripts/com.devon-technologies.think3/Reminders, and you can add your own if you like.Toolbar Scripts: You can customize a DEVONthink toolbar to add buttons that run specific AppleScripts. Although DEVONthink includes no prewritten toolbar scripts, you can add your own to
~/Library/ApplicationScripts/com.devon-technologies.think3/Toolbar. You must then quit and reopen DEVONthink, and then choose View > Customize Toolbar to add your custom script to the toolbar.Application-specific scripts: DEVONthink includes numerous scripts that appear on the system-wide Script
menu in other applications (such as DEVONagent, Mail, Outlook, and Safari), enabling you to import content of various kinds and formats into DEVONthink. These scripts are stored in ~/Library/Scripts/Applications/Application Name.A few examples for Safari:
Add linked images to DEVONthink: This script looks for thumbnails on a webpage that link to larger images, and downloads the full-size image files into DEVONthink.
Add links to DEVONthink: Similar to the last script, this one looks for links on the current webpage and adds each one to DEVONthink as a bookmark.
Add tabs to DEVONthink: This script adds bookmarks for all open Safari tabs to DEVONthink.
Folder Action Scripts: These scripts (located in
~/Library/Scripts/FolderActionScripts) are designed to be attached to folders such that when anything new appears in the folder, DEVONthink automatically imports it (with or without OCR) or indexes it.
DEVONthink 3 also offers a feature called “triggered scripts,” which lets you attach a specially written AppleScript to any item in your database and have that script run whenever you select that item. These scripts can be stored anywhere on your Mac, and DEVONthink 3 does not include any prewritten examples. I can’t think of any action I’d want to trigger automatically upon merely selecting an item in DEVONthink, so I won’t say more about this except to mention that you can find details in the documentation (search for “triggered scripts”).
Extra Scripts
Besides the automatically installed AppleScripts, DEVONthink includes 16 optional AppleScripts in the Support Assistant—choose Help > Support Assistant and click the Install Extras link at the bottom of the window to see and install them.
Writing Your Own Scripts
The best way to figure out how to automate something in DEVONthink using AppleScript is to open a related example script in Script Editor and see how it’s constructed. To view the complete list of AppleScript commands available in DEVONthink, in Script Editor, choose File > Open Dictionary, select DEVONthink 3, and click Choose. The most interesting terms are in the DEVONthink 3 Suite.
To learn more about using AppleScript generally, including tutorials and example scripts, visit MacOSXAutomation’s AppleScript page or the MacScripter website. DEVONthink’s documentation also has helpful information about getting started with DEVONthink-specific AppleScripts; see the “Basic AppleScript Terminology” topic. For more on scripting DEVONthink specifically, try the Learn how to automate DEVONthink Pro category within the DEVONtechnologies discussion forum.
Use Smart Templates
Earlier, in Template, I described how to create documents from prebuilt templates and edit those templates or create your own. I also mentioned a variant called a smart template, which also appears in the Data > New from Template submenu but is composed of AppleScript rather than a simple document with placeholders. I’d like to say a bit more about smart templates here.
Smart Templates enable you to perform any number of complex automated actions in the course of creating a new DEVONthink document. For example:
The Daily Journal smart template (in Data > New from Template > Productivity) creates a document that includes a quote (fetched from a web service) and the day’s news headlines (fetched from another web service).
The Project smart template (in the same submenu) creates a group tag hierarchy, which can include contact information selected from the Contacts app and a project name that you’re prompted to provide.
A smart template can be interactive, asking you to supply information that it then uses when creating your new document(s), tag(s), or group(s); it can also use logic to analyze or process information and behave differently depending on any of numerous variables, including information found online.
However, unlike smart groups, smart rules, and conventional templates, smart templates are not easy to create. They’re built almost entirely in AppleScript, and so unless you have a fair bit of facility with the language, creating a smart template that works just the way you want may be challenging.
I suggest, as does the DEVONthink documentation, that you start by opening, examining, and modifying (copies of) some of the existing smart templates to see how things are done. You can find these in subfolders of ~/Library/Application Support/DEVONthink 3/Templates.noindex; they’re the packages with the .templatescriptd extension. Right-click (or Control-click) one of these, choose Show Package Contents from the contextual menu, and examine the files inside—especially Contents/Resources/Scripts/main.scpt.