Automation : Basic AppleScript Terminology

Quick links:

Talking to DEVONthink
DEVONthink's dictionary
Using Locations
Working with a selection

Basic AppleScript Terminology

AppleScript is not a difficult language to learn. Its plain English approach of "talking" to applications and elements is easily understandable. However, like any language, there are some variations in the words you can use; dialects, if you will. AppleScript is implemented by the developer of an application, so the commands and parameters may be conceptually the same as another application's, but using a different term. This is certainly not meant to be a complete guide to AppleScripting DEVONthink, but what follows are some common terms or concepts you're likely to encounter. The examples here and in this chapter are meant to give you basic ideas about scripting DEVONthink.

Talking to DEVONthink

In AppleScript you "talk" to programs like DEVONthink using a tell statement, typically referring to an application either by its name, "DEVONthink 3", or its bundle identifier, "com.devon-technologies.think3". While these forms will work, they might become incompatible with a future version, e.g., DEVONthink 4, so we strongly recommend to talk to DEVONthink using the application ID DNtp, like in the following statement:

Example:

tell application id "DNtp"
close current database
end tell

DEVONthink's dictionary

AppleScript-capable applications have their commands, elements, and properties listed in an AppleScript dictionary. DEVONthink includes a large dictionary as a great reference for you. To view the dictionary, open the Script Editor application, select File > Open Dictionary and choose DEVONthink in the appearing window. You can also add DEVONthink to your Script Editor library. Select Window > Library, click the + button and choose DEVONthink. This way you keep DEVONthink's dictionary at hand.

Note: The use of the is almost always optional, but including it can make the script seem a bit less robotic. For example, both lines in this script are functionally the same:

Example:

tell application id "DNtp"
set state of children of current group to true
set the state of the children of the current group to true
end tell

As noted above, the dictionary is the best place to find specific terminology to be used with DEVONthink. However, here are two things to understand:

Records: Every item in a DEVONthink database is a record, a record with properties. Do a search for "record" in the dictionary and you'll see it's a fundamental unit with a wide range of properties associated with it. This means you won't be writing code like, get the second rich text file…. You will be dealing with records with a particular type, in this case rtf.

There are many commands specifically for use with records: create record with, exists record with…, etc. Also note there are some commands that require the term record. For example: move, delete, and convert. You will see a dictionary listing move record, so you can see the command isn't merely move, it's move record.

Parents and Children: Another concept to understand is parents & children. Generally speaking, these classes deal with the container or the contents of some object. The parent of an object is the group containing it. The children of a group are the immediate contents of that group, i.e., it does not list the children of sub-groups. Children can be documents or groups; parents will only be groups.

Example:

tell application id "DNtp"
set thisGroup to current group
name of (the children of thisGroup whose (type is XML))
end tell

Using Locations

One of the common tasks people want to perform with AppleScript is importing files to a specific group. In order to direct the files to a given location, you need to reference it properly. Below are three general options for choosing a location:

incoming group: This targets the Global Inbox, or the inbox of a database when using incoming group of current database.
current group: This targets the currently selected group in the current database.
display group selector: This shows the group selector so you can choose a location on demand.

There are many times you want to direct files into a specific group. That group may not be the current group you're in and you may not want to choose a destination each time. Here are two common ways of specifying a particular group in your database to be a destination group in your script:

get record at…: This command allows you to set a variable by specifying a group's location in your group structure. The location is a text string, always beginning with a forward slash denoting the root of the database.
get record with UUID…: When using an item link, you can use the alpha-numeric string from the reference URL to point to a specific item. (This command works with both groups and documents.) This form is very useful since it doesn't change when an item's name or location changes.

Example:

tell application id "DNtp"
set myGroup to get record at "/Inbox/New Files"
import "~/Desktop/001.txt" to myGroup
set groupTwo to get record with uuid "98BBF96D-7743-46C6-9EB4-51C6EF68373C"
import "~/Desktop/002.txt" to groupTwo
end tell

Working with a selection

Many times you want to process items you have selected in DEVONthink. Perhaps you want to generate a list of names and dates for use in a document you're working on. Below is a handler commonly seen in DEVONthink scripts:

repeat with thisRecord in (selection as list) … end repeat: This is a very common handler, used when processing a selection, single or multiple items.

Example:

tell application id "DNtp"
if selection is not {} then
set nameList to {}
repeat with thisRecord in (selection as list)
copy ((name of thisRecord) & ": " & (creation date of thisRecord as string) & return) to end of nameList
end repeat
create record with {name:"Files", type:text, content: (nameList as string)} in incoming group
end if
end tell