Home | Appendix

Quick links: |  | Script Actions External Scripts Embedded Scripts Terminology External Debugging

|  |  | Smart Item Scripts

Smart item scripts are AppleScripts or JavaScripts run by specialized actions in a smart rule or batch processing. These actions allow you to extend the possibilities beyond the already powerful pre-defined actions. There are three actions you will use: one simply runs code on matched items, the other can also handle incoming and outgoing data, and one handles input. Script Actions Apply Script: This action runs AppleScript or JavaScript for Automation (JXA) code on the matched items. It runs as a standalone action, not receiving or passing along any data to its surrounding actions. It is often used for specific functions not available in the pre-defined actions. For example, using a specific tag on a document for filing or setting metadata. This action also has the advantage of being able to quickly process multiple documents. Set Script Input: This optional action functions as a variable, a temporary container for a value to be passed on to the `Script with Input/Output` action. The input can be set from many sources, like a chat response, a document's aliases, etc. However, it only accepts strings, numbers, or URLs. Script with Input/Output: This powerful action contains a script handler that receives input and can also send information to actions that follow it. Getting information from other steps in your process opens up new opportunities for deeper automation. To accept input from a previous action, use the `Set Script Input` action. If you're using output from the action, it can be accessed with a Script Output placeholder. If you examine some of the built-in scripts, you can see examples of input and output. For an example output only, the `Coordinates` script gets the latitude and longitude from the geolocation of a record, something for which there is no specific smart action. So it returns those values to be used with a subsequent action via the `Script Output` placeholder, perhaps one that sets custom metadata. For an input example, see the `Annotation – Append Text` script. It receives input from a `Set Script Input` action to be added to the end of the document's annotation file. External Scripts External scripts are accessible to any rule or configuration. So if you have code that would be useful in more than one process, saving them externally is a good idea. To run an external script, add the action, select `External`and choose one of the installed scripts. In the `~/Library/Application Scripts/com.devon-technologies.think/` directory you can find the scripts for the `Apply Script` action in `Smart Rules` and those for `Script with Input/Output` in `Script Output`. And of course you can add any of your own scripts. We have compiled a list of the pre-installed scripts, for everyday use and your education. Embedded Scripts If you are writing a script for a specific smart rule or batch process, you can use an embedded script. The code is part of the action and can't be used by another other smart rule or configuration. To create an embedded script, add an `Apply Script` action then choose AppleScript or JavaScript. Click the `Edit Script` button and a popup will appear with a pre-built handler in place. Add your code, and press the compile button, the one with the stylized eye, to make sure it compiles correctly. If it does, you will see the code format itself subtly. If not, you will hear a system alert. When done, click outside the popup to dismiss it. For those new to scripting, there is a pre-built handler for each type of action. Terminology Apply Rule: These scripts are defined by this handler: `on performSmartRule(var)`, where `var` is the variable representing items matched by the smart rule.
Example: on performSmartRule(theRecords) tell application id "DNtp" repeat with theRecord in theRecords if (name of theRecord as string) contains "Piglet" then set state of theRecord to true end if end repeat end tell end performSmartRule
Script with Input/Output: These scripts are defined by this handler: `on scriptOutput(theRecord,theInput)`You can see there are two parameters for the handler: `theRecord` and `theInput`. In order to use the input parameter, it must be proceeded by a `Set Script Input` action. Here is an example of the handler:
Example: on scriptOutput(theRecord, theInput) tell application id "DNtp" set name of theRecord to (its name & "-" & theInput as string) return name of theRecord end tell end scriptOutput
External Debugging While there isn't a step-by-step logging of all actions in a smart rule, when you are using a script action, errors will be reported in the Log window or toolbar button. However, if you're writing the script in Apple's Script Editor, here are two core snippets you could use to develop and test the script:
Example: tell application id "DNtp" to my performSmartRule(selected records) on performSmartRule(theRecords) … end performSmartRule tell application id "DNtp" to my scriptOutput(selected record 1,"") on scriptOutput(theRecord,theInput) … end scriptOutput
After you have the script working, you can copy and paste it into the script in your smart item. PRO If you have external AI set up and a code-compatible model, you can use DEVONthink's Script Assistant. Choose the AI model and enter a description of the desired script in the prompt field, then press the ↩ Return key to compose and refine a script.